def add_new_user(session,
account_id,
username,
email,
role,
notify_on_events="NO",
return_type=None,
**kwargs):
"""
Add new user
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type account_id: str
:param account_id: The VPSAOS account 'id' value as returned by
get_all_accounts. For example: '91ea5bd5cdc04adb9f5e3c00a346c463'.
Required.
:type username: str
:param username: Username. Required.
:type email: str
:param email: User Email. Required.
:type: role: str
:param role: Role. Required.
:type: notify_on_events: str
:param notify_on_events: "Yes" if notify on events, else "No"
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_account_id(account_id)
verify_boolean(notify_on_events, "notify_on_events")
verify_field(username, "username")
verify_email(email)
verify_field(role, "role")
path = "/api/zios/users.json"
body_values = {
'account_id': account_id,
'username': username,
'email': email,
'role': role,
'notify_on_events': notify_on_events
}
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def break_ros_backup_job(session,
ros_backup_job_id,
purge_data,
delete_snapshots,
return_type=None,
**kwargs):
"""
Breaks a remote object storage backup job. This action is irreversible.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type ros_backup_job_id: str
:param ros_backup_job_id: The remote object storage backup job 'name'
value as returned by get_all_ros_backup_jobs. For example:
'bkpjobs-00000001'. Required.
:type purge_data: str
:param purge_data: If set to 'YES', all data related to this backup job
will be deleted on the remote object storage destination endpoint. If
'NO', the data will remain on the endpoint. Required.
:type delete_snapshots: str
:param delete_snapshots: If set to 'YES', all snapshots created by the
specified policy will be deleted. If 'NO', they won't. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_ros_backup_job_id(ros_backup_job_id)
body_values = {
'purge_data': verify_boolean(purge_data, "purge_data"),
"delete_snapshots": verify_boolean(delete_snapshots,
"delete_snapshots")
}
path = '/api/object_storage_backup_jobs/{0}/break.json' \
.format(ros_backup_job_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def set_recycle_bin(session, recycle_bin, return_type=None, **kwargs):
"""
Turns the recycle bin on or off globally for all pools.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type recycle_bin: str
:param recycle_bin: If set to 'YES', deleted volumes are moved to the
recycle bin, where they may be restored in case of accidental
deletion (volumes are permanently deleted from the recycle bin after
seven days). If set to 'NO', deleted volumes are immediately deleted.
The default value is 'YES'. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
recycle_bin = verify_boolean(recycle_bin, "recycle_bin")
body_values = {'recyclebin': recycle_bin}
path = '/api/settings/set_recycle_bin.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def set_pool_cache(session, pool_id, cache, return_type=None, **kwargs):
"""
Toggle the SSD caching for a pool.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type pool_id: str
:param pool_id: The pool 'name' value as returned by get_all_pools. For
example: 'pool-00000001'. Required.
:type cache: str
:param cache: Set to 'YES' to turn SSD caching on for this pool, or
'NO' to turn it off. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_pool_id(pool_id)
cache = verify_boolean(cache, "cache")
body_values = {'command': 'Enable' if cache == 'YES' else 'Disable'}
path = '/api/pools/{0}/toggle_cache.json'.format(pool_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def ssl_termination(session, is_terminate, return_type=None, **kwargs):
"""
VPSAOS SSL termination
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type is_terminate: bool
:param is_terminate: True iff terminate SSL. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
is_terminate = verify_boolean(is_terminate, is_terminate)
path = "/api/zios/settings/ssl_termination.json"
body_values = {"ssltermination": "on" if is_terminate else "off"}
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def enable_cache(session, pool_id, cowcache, return_type=None, **kwargs):
verify_pool_id(pool_id)
cowcache = verify_boolean(cowcache, "cowcache")
cowcache = str(cowcache == 'YES').lower()
path = '/api/pools/{0}'.format(pool_id)
body_values = {'command': 'enable', 'cowcache': cowcache}
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def delete_account(session,
account_id,
force='NO',
return_type=None,
**kwargs):
"""
Delete a VPSAOS account.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type account_id: str
:param account_id: The VPSAOS account 'id' value as returned by
get_all_accounts. For example: '91ea5bd5cdc04adb9f5e3c00a346c463'.
Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSAOS to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_account_id(account_id=account_id)
verify_boolean(force, 'force')
path = "/api/zios/accounts/{0}.json".format(account_id)
body_values = {'force': force}
return session.delete_api(path=path,
body=body_values,
secure=True,
return_type=return_type,
**kwargs)
def set_smb_trusted_domains(session, allow_trusted_domains, force='NO',
return_type=None, **kwargs):
"""
Sets whether or not the SMB/CIFS server should allow Active Directory
trusted domains.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type allow_trusted_domains: str
:param allow_trusted_domains: For VPSAs joined to an Active Directory
domain, if set to 'YES', Active Directory trusted domains will be
allowed. If set to 'NO', Active Directory trusted domains will not be
allowed. The default value is 'YES'. Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
allow_trusted_domains = verify_boolean(allow_trusted_domains,
"allow_trusted_domains")
force = verify_boolean(force, "force")
body_values = {'allow': allow_trusted_domains, 'force': force}
path = '/api/settings/smb_trusted_domains.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def create_nas_group(session,
groupname,
nfs_gid=None,
smb='NO',
return_type=None,
**kwargs):
"""
Creates a NAS user. Either nfs_gid must be specified or smb must be set
to 'YES' (or both).
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type groupname: str
:param groupname: The NAS group's groupname. Required.
:type nfs_gid: int
:param nfs_gid: When using NFS, the GID for the NFS user. This should
correspond to the group's GID in the client system's /etc/groups file.
"root" and "nogroup" groups are statically defined by the VPSA.
Optional.
:type smb: str
:param smb: When using SMB, if set to 'YES', this group will be usable by
SMB/CIFS clients. If set to 'NO', this group won't be usable by
SMB/CIFS clients. Optional (set to 'NO' by default).
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
groupname = verify_group_name(groupname)
smb = verify_boolean(smb, "smb")
_check_nfs_gid(nfs_gid, smb)
body_values = {'groupname': groupname, 'smb': smb}
if nfs_gid is not None:
body_values['nfs_gid'] = nfs_gid
path = '/api/nas/groups.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def remove_mirror_snapshot_policy(session,
mirror_id,
policy_id,
delete_snapshots,
return_type=None,
**kwargs):
"""
Removes a snapshot policy from an existing mirror job. A mirror job must
always have at least one snapshot policy attached. This should only be
initiated from the source VPSA. e.g. the mirror job ID should start with
"srcjvpsa-".
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type mirror_id: str
:param mirror_id: The mirror job 'job_name' value as returned by
get_all_mirrors. For example: 'srcjvpsa-00000001'. Required.
:type policy_id: str
:param policy_id: The snapshot policy 'name' value as returned by
get_all_snapshot_policies. For example: 'policy-00000001'. Required.
:type delete_snapshots: str
:param delete_snapshots: If set to 'YES', all snapshots created by the
specified policy will be deleted. If 'NO', they won't. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_mirror_id(mirror_id)
verify_policy_id(policy_id)
delete_snapshots = verify_boolean(delete_snapshots, "delete_snapshots")
body_values = {
'policyname': policy_id,
'delete_snapshots': delete_snapshots
}
path = '/api/mirror_jobs/{0}/detach_snapshot_policy.json'.format(mirror_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def replace_drive(session,
drive_id,
to_drive_id,
force='NO',
return_type=None,
**kwargs):
"""
Replaces a drive, identified by drive_id parameter, with a new unallocated
drive, identified by to_drive_id parameter, in a RAID group. The
replacement drive must not be currently allocated to a RAID group.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type drive_id: str
:param drive_id: The drive to be replaced. This is the drive 'name' value
as returned by get_all_drives. For example: 'volume-00002a73'.
Required.
:type to_drive_id: str
:param to_drive_id: The replacement drive. This is the drive 'name' value
as returned by get_all_drives. For example: 'volume-00002a76'.
Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_volume_id(drive_id)
verify_volume_id(to_drive_id)
force = verify_boolean(force, "force")
body_values = {'toname': to_drive_id, 'force': force}
path = '/api/drives/{0}/replace.json'.format(drive_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def add_hot_spare_to_raid_group(session,
raid_id,
drive_id,
force='NO',
return_type=None,
**kwargs):
"""
Attaches a drive as a hot spare to an existing RAID group, as identified
by the drive_id attribute.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type raid_id: str
:param raid_id: The RAID group 'name' value as returned by
get_all_raid_groups. For example: 'RaidGroup-1'. Required.
:type drive_id: str
:param drive_id: The drive 'name' value as returned by get_all_drives.
For example: 'volume-00002a73'. Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_raid_id(raid_id)
verify_drives(drive_id)
force = verify_boolean(force, "force")
body_values = {'disk': drive_id, 'force': force}
path = '/api/raid_groups/{0}/hot_spares.json'.format(raid_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def failover_controller(session,
confirm,
force='NO',
return_type=None,
**kwargs):
"""
Initiates a failover of the current active controller to the standby
controller.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type confirm: bool
:param confirm: If True, failover will be performed. This is a safeguard
for this function since it requires no other arguments.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
if not confirm:
raise ValueError('The confirm parameter is not set to True - '
'failover will not be performed.')
force = verify_boolean(force, "force")
body_values = {'force': force}
path = '/api/vcontrollers/failover.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def update_mirror_wan_optimization(session,
mirror_id,
wan_optimization,
return_type=None,
**kwargs):
"""
Change the WAN optimization setting for a mirror job. This should only be
initiated from the source VPSA. e.g. the mirror job ID should start with
"srcjvpsa-".
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type mirror_id: str
:param mirror_id: The mirror job 'job_name' value as returned by
get_all_mirrors. For example: 'srcjvpsa-00000001'. Required.
:type wan_optimization: str
:param wan_optimization: If set to 'YES', the mirror will attempt to
reduce the amount of data needing to be synchronized to the remote
side at the expense of more load on the source VPSA. If set to 'NO',
more data will be sent by the mirror with less load on the source
VPSA. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_mirror_id(mirror_id)
wan_optimization = verify_boolean(wan_optimization, "wan_optimization")
path = '/api/mirror_jobs/{0}/set_wan_optimization.json'.format(mirror_id)
body_values = {'wan_optimization': wan_optimization}
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def update_ros_backup_job_compression(session,
ros_backup_job_id,
compression,
return_type=None,
**kwargs):
"""
Updates the compression setting for a remote object storage backup job.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type ros_backup_job_id: str
:param ros_backup_job_id: The remote object storage backup job 'name'
value as returned by get_all_ros_backup_jobs. For example:
'bkpjobs-00000001'. Required.
:type compression: str
:param compression: If set to 'YES', backup data will be compressed in
flight. If 'NO', backup data will not be compressed. Set to 'YES' by
default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_ros_backup_job_id(ros_backup_job_id)
body_values = {'compression': verify_boolean(compression, 'compression')}
path = '/api/object_storage_backup_jobs/{0}/compression.json' \
.format(ros_backup_job_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def set_pool_cowcache(session, pool_id, cowcache, return_type=None, **kwargs):
"""
Toggle the CoW caching for a pool.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type pool_id: str
:param pool_id: The pool 'name' value as returned by get_all_pools. For
example: 'pool-00000001'. Required.
:type cowcache: str
:param cowcache: If set to 'YES', the pool's copy on write (CoW)
operations will occur on SSD for elevated performance instead of
directly on the underlying drives. In certain extreme scenarios, this
may be detrimental. It is suggested to leave 'YES' unless instructed
by a Zadara Storage representative. Required.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_pool_id(pool_id)
cowcache = verify_boolean(cowcache, "cowcache")
body_values = {'cowcache': str(cowcache == 'YES').lower()}
path = '/api/pools/{0}/cow_cache.json'.format(pool_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def shred_drive(session, drive_id, force='NO', return_type=None, **kwargs):
"""
Initializes drive shredding for an individual drive. Drive must not be
participating in a RAID group. CAUTION: This procedure will permanently
destroy data and is irreversible.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type drive_id: str
:param drive_id: The drive 'name' value as returned by get_all_drives.
For example: 'volume-00002a73'. Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_volume_id(drive_id)
force = verify_boolean(force, "force")
body_values = {'force': force}
path = '/api/drives/{0}/shred.json'.format(drive_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def set_smb_charset(session, charset, force='NO', return_type=None, **kwargs):
"""
Sets the character set used by the SMB/CIFS server for all SMB/CIFS
shared volumes.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type charset: str
:param charset: If set to 'UTF-8', the SMB/CIFS character set will be
UTF-8. If set to 'ISO-8859-1', it will be set to ISO-8859-1. 'UTF-8'
is the default value. Required.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_charset(charset)
force = verify_boolean(force, "force")
body_values = {'charset': charset, 'force': force}
path = '/api/settings/smb_charset.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def create_ros_restore_job(session,
display_name,
ros_destination_id,
pool_id,
restore_mode,
volume_name,
local_snapshot_id,
object_store_key,
crypt,
dedupe='NO',
compress='NO',
return_type=None,
**kwargs):
"""
Creates a new remote object storage backup job. Backups are based on
snapshots taken by the specified snapshot policy.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the remote object storage
restore job. For example: 'PDF archive restore'. May not contain a
single quote (') character. Required.
:type ros_destination_id: str
:param ros_destination_id: The remote object storage destination 'name'
value as returned by get_all_ros_destinations for the destination
where the snapshot is stored. For example: 'obsdst-00000001'.
Required.
:type pool_id: str
:param pool_id: The pool 'name' value as returned by get_all_pools where
the snapshot will be restored. For example: 'pool-00000001'. The
volume will be created on this pool. Required.
:type restore_mode: str
:param restore_mode: This parameter expects one of three values:
'restore', 'clone', or 'import_seed'. When set to 'restore', the
volume can be immediately attached to servers; data is retrieved from
object storage on demand and in a background process; and all data
will eventually be restored. When set to 'clone', the volume can be
immediately attached to servers; and starting with zero capacity, data
is retrieved from object storage only on-demand when accessed by the
attached servers. When set to 'import_seed', a full capacity clone is
created, including snapshot time-stamping; The volume can be attached
to servers only after the volume's data was fully retrieved from
object storage; use this mode to import initial data seed for remote
mirroring. Required.
:type volume_name: str
:param volume_name: A text label to assign to the restored volume. For
example: 'pdf-files'. May not contain a single quote (') character.
Required.
:type local_snapshot_id: str
:param local_snapshot_id: Either this or object_store_key is required.
If using local_snapshot_id, the desired snapshot 'name' is passed as
returned by get_all_snapshots (with the ros_backup_job_id specified).
For example: 'snap-00000001'. Optional.
:type object_store_key: str
:param object_store_key: Either this or local_snapshot_id is required. If
using object_store_key, this is the full object storage key for the
"path" to the individual snapshot to be restored. For example:
"cloud1.C97E9A00ADE7489BB08A9AB3B0B6484F/myvpsa.vsa-00000169/
myvol.volume-00000011/2015-07-01T09:26:01+0000_snap-0000003e/". This
is useful when there is no local_snapshot_id to reference; for
example, if the snapshot is being restored to a different VPSA than
the original source. Optional.
:type crypt: str
:param crypt: If set to 'YES', the resulting volume of the restoration
will be encrypted with the VPSA's encryption key. If 'NO', the
resulting volume will not be encrypted. Required.
:type dedupe: str
:param dedupe: If set to 'YES', deduplication will be enabled on the
volume. If 'NO', it won't. Optional.
:type compress: str
:param compress: If set to 'YES', compression will be enabled on the
volume. If 'NO', it won't. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_ros_destination_id(ros_destination_id)
verify_pool_id(pool_id)
verify_restore_mode(restore_mode)
body_values = {
'name': verify_field(display_name, "display_name"),
'remote_object_store': ros_destination_id,
'poolname': pool_id,
'mode': restore_mode,
'volname': verify_field(volume_name, "volume"),
'crypt': verify_boolean(crypt, "crypt")
}
if local_snapshot_id is None and object_store_key is None:
raise ValueError('Either "local_snapshot_id" or "object_store_key" '
'needs to be passed as a parameter.')
if local_snapshot_id is not None:
verify_snapshot_id(local_snapshot_id)
body_values['local_snapname'] = local_snapshot_id
if object_store_key is not None:
body_values['key'] = verify_field(object_store_key, "object_store_key")
if dedupe is not None:
body_values["dedupe"] = verify_boolean(dedupe, 'dedupe')
if compress is not None:
body_values["compress"] = verify_boolean(compress, 'compress')
path = '/api/object_storage_restore_jobs.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_ros_backup_job(session,
display_name,
ros_destination_id,
sse,
volume_id,
policy_id,
compression='YES',
return_type=None,
**kwargs):
"""
Creates a new remote object storage backup job. Backups are based on
snapshots taken by the specified snapshot policy.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the remote object storage
backup job. For example: 'Daily S3 Backup'. May not contain a single
quote (') character. Required.
:type sse: str
:param sse: The remote object storage destination SSE:
'NO', 'AES256', 'KMS', 'KMSKEYID Required.
:type ros_destination_id: str
:param ros_destination_id: The remote object storage destination 'name'
value as returned by get_all_ros_destinations. For example:
'obsdst-00000001'. Required.
:type volume_id: str
:param volume_id: The volume 'name' value as returned by get_all_volumes
for the volume to be backed up. For example: 'volume-00000001'.
Required.
:type policy_id: str
:param policy_id: The snapshot policy 'name' value as returned by
get_all_snapshot_policies. For example: 'policy-00000001'. This
policy will determine the frequency and retention of backups for this
job. Required.
:type compression: str
:param compression: If set to 'YES', backup data will be compressed in
flight. If 'NO', backup data will not be compressed. Set to 'YES' by
default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
verify_ros_destination_id(ros_destination_id)
verify_volume_id(volume_id)
verify_policy_id(policy_id)
body_values = {
'name': display_name,
'destination': ros_destination_id,
'volume': volume_id,
'policy': policy_id,
'sse': sse,
'compression': verify_boolean(compression, "compression")
}
path = '/api/object_storage_backup_jobs.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def update_ros_destination(session,
ros_destination_id,
bucket=None,
endpoint=None,
username=None,
password=None,
public=None,
use_proxy=None,
proxy_host=None,
proxy_port=None,
proxy_username=None,
proxy_password=None,
return_type=None,
**kwargs):
"""
Updates options for an existing remote object storage destination.
Parameters set to 'None' will not have their existing values changed.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type ros_destination_id: str
:param ros_destination_id: The remote object storage destination 'name'
value as returned by get_all_ros_destinations. For example:
'obsdst-00000001'. Required.
:type bucket: str
:param bucket: See documentation for create_ros_destination. Optional.
:type endpoint: str
:param endpoint: See documentation for create_ros_destination. Optional.
:type username: str
:param username: See documentation for create_ros_destination. Optional.
:type password: str
:param password: See documentation for create_ros_destination. Optional.
:type public: str
:param public: See documentation for create_ros_destination. Optional.
:type use_proxy: str
:param use_proxy: See documentation for create_ros_destination. Optional.
:type proxy_host: str
:param proxy_host: See documentation for create_ros_destination.
Optional.
:type proxy_port: str
:param proxy_port: See documentation for create_ros_destination.
Optional.
:type proxy_username: str
:param proxy_username: See documentation for create_ros_destination.
Optional.
:type proxy_password: str
:param proxy_username: See documentation for create_ros_destination.
Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_ros_destination_id(ros_destination_id)
body_values = {}
if bucket is not None:
body_values['bucket'] = verify_field(bucket, "bucket")
if endpoint is not None:
body_values['endpoint'] = endpoint
if username is not None:
body_values['username'] = verify_field(username, "username")
if password is not None:
body_values['password'] = verify_field(password, "password")
if public is not None:
public = verify_boolean(public, "public")
body_values['connectVia'] = 'public' if public == 'YES' else 'fe'
if use_proxy is not None:
use_proxy = verify_boolean(use_proxy, "use_proxy")
body_values['use_proxy'] = str(use_proxy == 'YES').lower()
if proxy_host is not None or use_proxy == 'YES':
body_values['proxyhost'] = proxy_host
if proxy_port is not None or use_proxy == 'YES':
body_values['proxyport'] = verify_port(proxy_port)
if proxy_username is not None:
body_values['proxyuser'] = verify_field(proxy_username,
"proxy_username")
if proxy_password is not None:
body_values['proxypassword'] = verify_field(proxy_password,
"proxy_password")
if not body_values:
raise ValueError('At least one of the following must be set: '
'"bucket", "endpoint", "username", "password", '
'"public", "use_proxy", "proxy_host", "proxy_port", '
'"proxy_username", "proxy_password"')
path = '/api/object_storage_destinations/{0}.json' \
.format(ros_destination_id)
return session.put_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_server(session, display_name, ip_address=None, iqn=None,
vpsa_chap_user=None, vpsa_chap_secret=None,
host_chap_user=None, host_chap_secret=None,
ipsec_iscsi='NO', ipsec_nfs='NO', force='NO',
return_type=None, **kwargs):
"""
Creates a new server. A valid server record must be attached to a volume
before a client with the corresponding IP or IQN can access the volume.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the server. For example:
'web-01', 'database', etc. May not contain a single quote (')
character. Required.
:type ip_address: str
:param ip_address: If using NFS/CIFS, the IP address or subnet as defined
in CIDR notation of the server. Either ip_address or iqn must be
passed to this function (or both). Optional.
:type iqn: str
:param iqn: If using iSCSI/iSER, the IQN of the server. For example -
"iqn.1993-08.org.debian:01:dea714656496". Either ip_address or iqn
must be passed to this function (or both). Optional.
:type vpsa_chap_user: str
:param vpsa_chap_user: When using iSCSI/iSER, the CHAP user for the VPSA.
This would be typically entered in the server's iSCSI/iSER initiatior
configuration. If set to 'None', a VPSA CHAP user will be auto
generated. Optional.
:type vpsa_chap_secret: str
:param vpsa_chap_secret: When using iSCSI/iSER, the CHAP secret for the
VPSA. This would be typically entered in the server's iSCSI/iSER
initiatior configuration. If set to 'None', a VPSA CHAP secret will
be auto generated. Must be between 12 to 16 characters in length.
Optional.
:type host_chap_user: str
:param host_chap_user: When using iSCSI/iSER, the CHAP user for the
server. If defined, the VPSA will use this to complete mutual CHAP
authentication with the server. Note: for Windows systems, the host
CHAP user must be the server's IQN. If set to 'None', mutual CHAP
won't be used. Optional.
:type host_chap_secret: str
:param host_chap_user: When using iSCSI/iSER, the CHAP secret for the
server. If defined, the VPSA will use this to complete mutual CHAP
authentication with the server. If set to 'None', mutual CHAP won't
be used. Must be between 12 to 16 characters in length. Optional.
:type ipsec_iscsi: str
:param ipsec_iscsi: When accessing iSCSI/iSER block volumes from this
server, if set to 'YES', IPSec encryption will be mandated when
connecting from this server. If 'NO', IPSec won't be used. Set to
'NO' by default. Optional.
:type ipsec_nfs: str
:param ipsec_nfs: When accessing NFS NAS shares from this server, if set
to 'YES', IPSec encryption will be mandated when connecting from this
server. If 'NO', IPSec won't be used. Set to 'NO' by default.
Optional.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
if ip_address is None and iqn is None:
raise ValueError('Either ip_address or iqn parameter must be '
'defined.')
body_values = {'display_name': display_name,
'ipsec_iscsi': verify_boolean(ipsec_iscsi, "ipsec_iscsi"),
'ipsec_nfs': verify_boolean(ipsec_nfs, "ipsec_nfs"),
'force': verify_boolean(force, "force")}
if ip_address is not None:
body_values['iscsi'] = ip_address
if iqn is not None:
if not is_valid_iqn(iqn):
raise ValueError('{0} is not a valid iSCSI/iSER IQN.'
.format(iqn))
body_values['iqn'] = iqn
if vpsa_chap_user is not None:
body_values['vpsachapuser'] = verify_field(vpsa_chap_user,
"vpsa_chap_user")
if vpsa_chap_secret is not None:
body_values['vpsachapsecret'] = verify_field(vpsa_chap_secret,
"vpsa_chap_secret")
if host_chap_user is not None:
body_values['hostchapuser'] = verify_field(host_chap_user,
"host_chap_user")
if host_chap_secret is not None:
body_values['hostchapsecret'] = verify_field(host_chap_secret,
"host_chap_secret")
path = '/api/servers.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def attach_servers_to_volume(session, servers, volume_id, access_type=None,
readonly='NO', force='NO', return_type=None,
**kwargs):
"""
Attaches one or more servers to a volume.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type servers: str
:param servers: A comma separated string of servers with no spaces
around the commas. The value must match server's 'name'
attribute. For example: 'srv-00000001,srv-00000002'. Required.
:type volume_id: str
:param volume_id: The volume 'name' value as returned by get_all_volumes.
For example: 'volume-00000001'. Required.
:type access_type: str
:param access_type: When to an NAS share volume, if set to 'NFS', only NFS
access will be allowed from this server. If set to 'SMB', only
SMB/CIFS will be allowed from this server. If set to None, both NFS
and SMB/CIFS will be allowed from this server. Note that when using
None, the ip address for the server must be defined in CIDR format,
even if it's a single host ending in /32. Not relevant for iSCSI
volumes. Optional.
:type readonly: str
:param readonly: If set to 'YES', the share will only be readable by this
server. If set to 'NO', this server will be able to read and write to
the share. Optional.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_server_id(servers)
verify_volume_id(volume_id)
verify_access_type(access_type)
body_values = {'volume_name': volume_id}
if access_type is not None:
verify_access_type(access_type)
# This allows an extra option through the command line utility
access_type = None if access_type == 'BOTH' else access_type
body_values['access_type'] = access_type
readonly = verify_boolean(readonly, "readonly")
body_values['readonly'] = readonly
force = verify_boolean(force, "force")
body_values['force'] = force
path = '/api/servers/{0}/volumes.json'.format(servers)
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def update_snapshot_policy(session, policy_id, create_policy=None,
local_delete_policy=None,
remote_delete_policy=None, display_name=None,
allow_empty=None, return_type=None, **kwargs):
"""
Change various settings related to a snapshot policy. These changes will
be propagated to any local volume, remote mirror job, or remote object
storage backup job that uses this policy. Parameters set to 'None' will
not have their existing values changed.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type policy_id: str
:param policy_id: The snapshot policy 'name' value as returned by
get_all_snapshot_policies. For example: 'policy-00000001'. Required.
:type create_policy: str
:param create_policy: See documentation for create_snapshot_policy.
Optional.
:type local_delete_policy: int
:param local_delete_policy: See documentation for create_snapshot_policy.
Optional.
:type remote_delete_policy: int
:param remote_delete_policy: See documentation for create_snapshot_policy.
Optional.
:type display_name: str
:param display_name: A text label to assign to the new snapshot policy.
:type allow_empty: str
:param allow_empty: See documentation for create_snapshot_policy.
Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_policy_id(policy_id)
body_values = {}
if create_policy is not None:
verify_policy_creation(create_policy)
body_values['create_policy'] = create_policy
if local_delete_policy is not None:
if local_delete_policy < 0:
raise ValueError('The local_delete_policy parameter must not be '
'negative ("{0}" was passed).'
.format(local_delete_policy))
body_values['delete_policy'] = 'N' + str(local_delete_policy)
if remote_delete_policy is not None:
if remote_delete_policy < 0:
raise ValueError('The remote_delete_policy parameter must not be '
'negative ("{0}" was passed).'
.format(remote_delete_policy))
body_values['destination_policy'] = 'N' + str(remote_delete_policy)
if allow_empty is not None:
body_values['empty'] = verify_boolean(allow_empty, 'allow_empty')
if display_name is not None:
body_values['display_name'] = display_name
if not body_values:
raise ValueError('At least one of the following must be set: '
'"display_name", "create_policy", '
'"local_delete_policy", "remote_delete_policy", '
'"display_name", "allow_empty"')
path = '/api/snapshot_policies/{0}.json'.format(policy_id)
return session.put_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def create_raid_group(session,
display_name,
protection,
disk,
stripe_size=64,
hot_spare='NO',
force='NO',
return_type=None,
**kwargs):
"""
Creates a new RAID group from comma separated list of drives in 'drive'
body parameter. The drives must not be currently participating in a RAID
group. Creation will fail if drives are not of identical capacity - this
can be overridden with the "force" parameter.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the RAID group. For
example: 'rg1', 'rg2', etc. May not contain a single quote (')
character. Required.
:type protection: str
:param protection: The type of RAID protection to use as represented by a
string. Must be one of: 'RAID1', 'RAID5', or 'RAID6'. Required.
:type disk: str
:param disk: A comma separated string of drives with no spaces around the
commas. The value must match drive's 'name' attribute. For example:
'volume-00002a73,volume-00002a74'. Required.
:type stripe_size: int
:param stripe_size: The stripe size for a RAID5 or RAID6 group, in KB.
Must be one of the following sizes: 4, 16, 32, 64, 128, or 256. It is
suggested to use the default value of 64KB unless you know what you're
doing. Required for RAID5/RAID6, irrelevant for RAID1.
:type hot_spare: str
:param hot_spare: If set to 'YES', a hot spare will be assigned to the
RAID group from the group of drives defined in the 'drive' parameter.
Optional, set to 'NO' by default.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:return: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
protection = verify_raid_type(protection)
verify_drives(disk)
verify_stripe_size(str(stripe_size))
hot_spare = verify_boolean(hot_spare, "hot_spare")
force = verify_boolean(force, "force")
body_values = {
'display_name': display_name,
'protection': protection,
'disk': disk,
'hot_spare': hot_spare,
'force': force
}
if protection == 'RAID1':
stripe_size = None
if stripe_size is not None:
body_values['stripe_size'] = stripe_size
# Inflect the required protection_width parameter from the count of
# elements in the 'disk' parameter instead of making the user pass it.
protection_width = len(disk.split(','))
if protection == 'RAID1':
if protection_width < 2 or protection_width > 3:
raise ValueError('A RAID1 group may only have 2 or 3 drives, but '
'{0} were supplied.'.format(protection_width))
if protection == 'RAID5':
if protection_width < 3 or protection_width > 5:
raise ValueError('A RAID5 group may only have 3-5 drives, but '
'{0} were supplied.'.format(protection_width))
if protection == 'RAID6':
if protection_width < 4 or protection_width > 10:
raise ValueError('A RAID6 group may only have 4-10 drives, but '
'{0} were supplied.'.format(protection_width))
body_values['protection_width'] = protection_width
path = '/api/raid_groups.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_ros_destination(session,
display_name,
bucket,
endpoint,
username,
password,
public,
use_proxy,
ros_type,
allow_lifecycle_policies=None,
proxy_host=None,
proxy_port=None,
proxy_username=None,
proxy_password=None,
return_type=None,
**kwargs):
"""
Creates a remote object storage destination. The VPSA can either connect
directly to the object storage endpoint, or through an HTTP/HTTPS proxy
server.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the remote object storage
destination. For example: 'zadarabackup-bucket in AWS East'. May not
contain a single quote (') character. Required.
:type bucket: str
:param bucket: The globally unique destination bucket identifier. For
example: 'zadarabackup-bucket'. May not contain a single quote (')
character. Required.
:type endpoint: str
:param endpoint: The hostname for the object storage endpoint. For
example, for S3 US East: 's3.amazonaws.com'. Required.
:type username: str
:param username: The username or access key ID for the object storage
endpoint. Required.
:type password: str
:param password: The password or secret access key for the object storage
endpoint. Required.
:type public: str
:param public: If set to 'YES', establishing the remote object storage
destination and all future remote object storage jobs occur over the
VPSA's public IP/interface (The VPSA must have a valid public IP and
setup). If 'NO', the relationship and remote object storage jobs will
occur using the same IP as connecting to the storage - in this case
the VPSA must be able to route to the remote object storage
destination in question via the VPSA's defined default gateway.
Required.
:type allow_lifecycle_policies: str
:param allow_lifecycle_policies: If set to 'YES', the VPSA will allow
bucket to have lifecycle policies. (Valid Only for AWS)
:type use_proxy: str
:param use_proxy: If set to 'YES', the VPSA will connect via an HTTP/HTTPS
proxy when addressing the object storage destination. If 'NO', a
direct connection will be used. Required.
:type proxy_host: str
:param proxy_host: When use_proxy is set to 'YES', this defines the DNS
hostname or IP of the HTTP/HTTPS proxy server to use. Optional.
:type proxy_port: str
:param proxy_port: When use_proxy is set to 'YES', this defines the port
number of the HTTP/HTTPS proxy server to use. Optional.
:type proxy_username: str
:param proxy_username: When use_proxy is set to 'YES', this defines the
proxy server username if proxy authentication is required. Optional.
:type proxy_password: str
:param proxy_username: When use_proxy is set to 'YES', this defines the
proxy server password if proxy authentication is required. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
bucket = verify_field(bucket, "bucket")
username = verify_field(username, "username")
password = verify_field(password, "password")
public = verify_boolean(public, "public")
use_proxy = verify_boolean(use_proxy, "use_proxy")
allow_lifecycle_policies = verify_boolean(allow_lifecycle_policies,
"allow_lifecycle_policies")
body_values = {
'name': display_name,
'bucket': bucket,
'endpoint': endpoint,
'username': username,
'type': ros_type,
'password': password,
'connectVia': 'public' if public == 'YES' else 'be',
'allow_lifecycle_policies': allow_lifecycle_policies
}
if use_proxy == 'YES':
body_values['proxyhost'] = proxy_host
body_values['proxyport'] = verify_port(proxy_port)
if proxy_username is not None:
body_values['proxyuser'] = verify_field(proxy_username,
"proxy_username")
if proxy_password is not None:
body_values['proxypassword'] = verify_field(
proxy_password, "proxy_password")
path = '/api/object_storage_destinations.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_zcs_container(session,
display_name,
zcs_image_id,
start,
use_public_ip='NO',
entrypoint=None,
volumes=None,
args=None,
envvars=None,
links=None,
memorypoolname=None,
return_type=None,
**kwargs):
"""
Creates a Zadara Container Services (ZCS) container. Requires a valid ZCS
image to instantiate from.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the ZCS container. For
example: 'web-01', 'database', etc. May not contain a single quote
(') character. Required.
:type zcs_image_id: str
:param zcs_image_id: The ZCS image 'name' value as returned by
get_all_zcs_images. For example: 'img-00000001'. The container will
be instantiated from this image. Required.
:type start: str
:param start: If set to 'YES', the ZCS container will be started
immediately after creation. If 'NO', it will not be started.
Required.
:type use_public_ip: str
:param use_public_ip: If set to 'YES', the ZCS container will listen on
VPSA's public IP address (only valid on VPSAs with a public IP
address). If set to 'NO', the container will listen on the same
private IP address that is used for addressing the storage. Optional
(set to 'NO' by default).
:type entrypoint: str
:param entrypoint: The full path to the program or script inside the ZCS
container to run when the container starts. For example:
"/usr/local/bin/entry.sh". It is important to define a correct
entrypoint either via this function or a "RUN" statement in the
Dockerfile, as when a VPSA needs to initiate a failover, the container
will be started automatically on the standby controller and the
container should automatically initiate any needed setup/program.
This should only be the path to the script/program. Only the path to
the script/program should be defined without arguments. To pass
arguments to the script/program, use the "args" parameter of this
function. Optional.
:type volumes: list, str
:param volumes: A Python list of Python dictionaries that contain several
pieces of information about the NAS share volumes (NFS/SMB only, no
iSCSI/ISER) that should be attached to the container when launched.
If passed as a string, a conversion to a Python list via json.loads
will be attempted. Every list item should be a dictionary that
contains the following keys:
* "name" - This key should contain the volume 'name' value as
returned by get_all_volumes. For example: 'volume-00000001'.
Required.
* "path" - This key should contain the full path inside of the
container where the volume will be mounted. If the path doesn't
exist in the container, it will be created. Required.
* "access" - If this key is set to 'rw', the volume will be mounted as
both readable and writable. If set to 'r', the volume will be
mounted as read only. Required.
An example would be:
[{"name":"volume-00000001","path":"/vol1","access":"rw"},
{"name":"volume-00000002","path":"/vol2","access":"r"}]
:type links: list, str
:param links: A Python list that contain container identifiers that will be
linked to the new container
An example would be:
["container-00000001" , "container-00000002"]
:type args: list, str
:param args: A Python list of Python dictionaries that contain arguments
to pass to the ZCS container entry point program or script as defined
by "entrypoint". If passed as a string, a conversion to a Python list
via json.loads will be attempted. Every list item should be a
dictionary that contains one key, "arg", whose value is the argument
to pass to the ZCS container. For example, if the entrypoint is
"/usr/sbin/sshd", these arguments will be passed to sshd. e.g.:
[{"arg":"-p 2222"},{"arg":"-f /etc/ssh/sshd_config"}]
:type envvars: list, str
:param envvars: A Python list of Python dictionaries that contain
information about environment variables to pass into the ZCS
container. If passed as a string, a conversion to a Python list via
json.loads will be attempted. Every list item should be a dictionary
that contains the the following keys:
* "variable" - This key should contain the name of the environment
variable to create. For example: "IP_ADDRESS".
* "value" - This key should contain the value for the corresponding
"variable". For example "172.20.125.100".
For example, say that part of the entry point script adds an item to a
Redis server. Environment variables could be used by the script to
determine the IP address, username, and password of the Redis server.
e.g.:
[{"variable":"IP_ADDRESS","value":"172.20.125.100"},
{"variable":"USERNAME","value":"zcs_container_01"},
{"variable":"PASSWORD","value":"very_strong_password"}]
:type memorypoolname: str
:param memorypoolname: Memory Pool ID
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, 'display_name')
verify_zcs_image_id(zcs_image_id)
start = verify_boolean(start, "start")
use_public_ip = verify_boolean(use_public_ip, "use_public_ip")
body_values = {
'name': display_name,
'imagename': zcs_image_id,
'start': start,
'use_public_ip': use_public_ip,
'entrypoint': entrypoint,
'link': links
}
if volumes is not None:
if type(volumes) is str:
volumes = json.loads(volumes)
if type(volumes) is not list:
raise ValueError('The passed "volumes" parameter is not a Python '
'list.')
for v in volumes:
if type(v) is not dict:
raise ValueError('Each item in the "volumes" list must be a '
'Python dictionary.')
if 'name' not in v:
raise ValueError('The required "volume" key was not found in '
'the name dictionary.')
if not is_valid_volume_id(v['name']):
raise ValueError('{0} is not a valid volume ID.'.format(
v['name']))
if 'path' not in v:
raise ValueError('The required "path" key was not found in '
'the volume dictionary.')
v['path'] = v['path'].strip()
if not is_valid_field(v['path']):
raise ValueError('"{0}" is not a valid ZCS container volume '
'mount point.'.format(v['path']))
if 'access' not in v:
raise ValueError('The required "access" key was not found in '
'the volume dictionary.')
if v['access'] not in ['rw', 'r']:
raise ValueError('"{0}" is not a valid "access" key in the '
'volume dictionary. Allowed values are: '
'"rw" or "r"'.format(v['access']))
body_values['volumes'] = volumes
if args is not None:
if type(args) is str:
args = json.loads(args)
if type(args) is not list:
raise ValueError('The passed "args" parameter is not a Python '
'list.')
for v in args:
if type(v) is not dict:
raise ValueError('Each item in the "args" list must be a '
'Python dictionary.')
if 'arg' not in v:
raise ValueError('The required "arg" key was not found in '
'the args dictionary.')
v['arg'] = v['arg'].strip()
if not is_valid_field(v['arg']):
raise ValueError('{0} is not a valid ZCS container argument '
'value.'.format(v['arg']))
body_values['args'] = args
if envvars is not None:
if type(volumes) is str:
envvars = json.loads(envvars)
if type(envvars) is not list:
raise ValueError('The passed "envvars" parameter is not a Python '
'list.')
for v in envvars:
if type(v) is not dict:
raise ValueError('Each item in the "envvars" list must be a '
'Python dictionary.')
if 'variable' not in v:
raise ValueError('The required "variable" key was not found '
'in the envvars dictionary.')
v['variable'] = v['variable'].strip()
if not is_valid_field(v['variable']):
raise ValueError('{0} is not a valid ZCS container '
'environment variable name.'.format(
v['variable']))
if 'value' not in v:
raise ValueError('The required "value" key was not found in '
'the envvars dictionary.')
# Don't strip leading or trailing whitespace here since a variable
# may contain any ad-hoc value depending on use case.
if not is_valid_field(v['value']):
raise ValueError('{0} is not a valid ZCS container '
'environment variable value.'.format(
v['value']))
body_values['envvars'] = envvars
if memorypoolname:
body_values['memorypoolname'] = memorypoolname
path = '/api/containers.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_pool(session,
display_name,
raid_groups,
capacity,
pooltype,
cache='NO',
cowcache='YES',
mode='stripe',
return_type=None,
**kwargs):
"""
Creates a new storage pool. A storage pool is an abstraction over RAID
groups. Multiple RAID groups can, and often do, participate in a single
storage pool. Volumes are then created on the storage pool, rather than
on the individual RAID groups.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the pool. For example:
'pool1', 'pool2', etc. May not contain a single quote (') character.
Required.
:type raid_groups: str
:param raid_groups: A comma separated string of RAID groups with no spaces
around the commas. The value must match RAID groups's 'name'
attribute. For example: 'RaidGroup-1,RaidGroup-2'. Required.
:type capacity: int
:param capacity: The total capacity in GB that will be created for the
storage pool. May not exceed the capacity of the combined underlying
RAID groups. Required.
:type pooltype: str
:param pooltype: Whether the pool should be set to Transactional,
Repository, or Archival type. Transactional is useful for more space
efficient writes on snapshots, but requires 4x as much memory,
therefore is limited to 20TB maximum space. Repository is a good
general purpose option that suits all workloads up to 100TB. Archival
can be used when >100TB pools are mandatory, but comes with
restrictions such as minimum 1 hour snapshot interval (instead of 1
minute). Please see the VSPA User Guide "Pools" section for a more
descriptive definition of these types. Must be the string
'Transactional', 'Repository', or 'Archival'. Required.
:type cache: str
:param cache: If set to 'YES', SSD caching will be enabled for this pool.
Optional, set to 'NO' by default.
:type cowcache: str
:param cowcache: If set to 'YES', the pool's copy on write (CoW)
operations will occur on SSD for elevated performance instead of
directly on the underlying drives. In certain extreme scenarios, this
may be detrimental. It is suggested to leave 'YES' unless instructed
by a Zadara Storage representative. Optional, set to 'YES' by
default.
:type mode: str
:param mode: If set to 'stripe', use striping to distribute data across
all participating RAID sets in the pool - this should always be used
for pools with more than one RAID group, unless you know what you're
doing. If set to 'simple', data will fill up one RAID group before
moving to the next (worse for performance than stripe). Single RAID
group pools will be set to 'simple' below automatically. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
capacity = verify_capacity(capacity, "Storage Pool")
verify_raid_groups(raid_groups)
verify_pool_type(pooltype)
cache = verify_boolean(cache, "cache")
mode = verify_mode(mode)
# If only one RAID group will be participating in this pool, force the
# mode to simple.
if len(raid_groups.split(',')) == 1:
mode = 'simple'
body_values = {
'display_name': display_name,
'capacity': '{0}G'.format(capacity),
'raid_groups': raid_groups,
'cache': cache,
'mode': mode
}
if pooltype == 'Transactional':
pooltype = 'Transactional Workloads'
else:
pooltype = '{0} Storage'.format(pooltype)
body_values['pooltype'] = pooltype
# CoW cache can only be enabled or disabled for pools where primary cache
# is enabled.
if cache == 'YES':
cowcache = verify_boolean(cowcache, "cowcache")
body_values['cowcache'] = str(cowcache == 'YES').lower()
path = '/api/pools.json'
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def create_snapshot_policy(session, display_name, create_policy,
local_delete_policy, remote_delete_policy,
allow_empty='NO', return_type=None, **kwargs):
"""
Creates a new snapshot policy. Can be used in conjunction with local
volume snapshots, remote mirror jobs, and/or remote object storage backup
jobs.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type display_name: str
:param display_name: A text label to assign to the snapshot policy. For
example: 'Daily Snapshots at 3 AM'. May not contain a single quote
(') character. Required.
:type create_policy: str
:param create_policy: The frequency to take snapshots. This is defined in
UNIX cron style format. For example: '0 3 * * *' would take a
snapshot at 3 AM every day. Alternatively, if "manual" is specified,
an "On Demand" snapshot policy will be created. Required.
:type local_delete_policy: int
:param local_delete_policy: The number of snapshots to retain on the local
VPSA before removing. For example, if 10 is specified, when the
11th snapshot is created, the oldest snapshot will be deleted.
If None is specified, this means "no deletion policy", i.e.,
snapshots will not be deleted. This is allowed only when creation
policy is 'manual'. Required.
:type remote_delete_policy: int
:param remote_delete_policy: The number of snapshots to retain on the
remote VPSA or object storage destination before removing. For
example, if 10 is specified, when the 11th snapshot is created, the
oldest snapshot will be deleted. If None is specified, this means
"no deletion policy", i.e., snapshots will not be deleted. Required.
:type allow_empty: str
:param allow_empty: If set to 'YES', snapshots will be taken even when no
data has been changed on the volume (creates empty snapshots). If set
to 'NO', snapshots will only be created if data has changed. Optional
(will be set to 'NO' by default).
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
display_name = verify_field(display_name, "display_name")
verify_policy_creation(create_policy)
allow_empty = verify_boolean(allow_empty, 'allow_empty')
body_values = {'name': display_name, 'create_policy': create_policy,
'empty': allow_empty}
if local_delete_policy is not None:
if local_delete_policy < 0:
raise ValueError('The local_delete_policy parameter must not be '
'negative ("{0}" was passed).'
.format(local_delete_policy))
body_values['delete_policy'] = 'N' + str(local_delete_policy)
else:
if create_policy != "manual":
raise ValueError('The local_delete_policy parameter cannot be '
'None unless the create_policy parameter is '
'"manual" ("{0}" create_policy was passed).'
.format(create_policy))
# Cannot pass None to API - must be empty string
body_values['delete_policy'] = ''
if remote_delete_policy is not None:
if remote_delete_policy < 0:
raise ValueError('The remote_delete_policy parameter must not be '
'negative ("{0}" was passed).'
.format(remote_delete_policy))
body_values['destination_policy'] = 'N' + str(remote_delete_policy)
else:
# Cannot pass None to API - must be empty string
body_values['destination_policy'] = ''
path = '/api/snapshot_policies.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def update_server(session, server_id, ip_address=None, iqn=None,
vpsa_chap_user=None, vpsa_chap_secret=None,
host_chap_user=None, host_chap_secret=None,
ipsec_iscsi=None, ipsec_nfs=None, force='NO',
return_type=None, **kwargs):
"""
Updates a server. Parameters set to 'None' will not have their existing
values changed. The server must not be attached to any volumes.
:type session: zadarapy.session.Session
:param session: A valid zadarapy.session.Session object. Required.
:type server_id: str
:param server_id: The server 'name' value as returned by get_all_servers.
For example: 'srv-00000001'. Required.
:type ip_address: str
:param ip_address: See documentation for create_server. Optional.
:type iqn: str
:param iqn: See documentation for create_server. Optional.
:type vpsa_chap_user: str
:param vpsa_chap_user: See documentation for create_server. Optional.
:type vpsa_chap_secret: str
:param vpsa_chap_secret: See documentation for create_server. Optional.
:type host_chap_user: str
:param host_chap_user: See documentation for create_server. Optional.
:type host_chap_secret: str
:param host_chap_user: See documentation for create_server. Optional.
:type ipsec_iscsi: str
:param ipsec_iscsi: See documentation for create_server. Optional.
:type ipsec_nfs: str
:param ipsec_nfs: See documentation for create_server. Optional.
:type force: str
:param force: If set to 'YES', ignore non-critical warnings and force the
VPSA to accept the request. If 'NO', return message on warning and
abort. Set to 'NO' by default. Optional.
:type return_type: str
:param return_type: If this is set to the string 'json', this function
will return a JSON string. Otherwise, it will return a Python
dictionary. Optional (will return a Python dictionary by default).
:rtype: dict, str
:returns: A dictionary or JSON data set as a string depending on
return_type parameter.
"""
verify_server_id(server_id)
body_values = {}
if ip_address is not None:
body_values['iscsi'] = ip_address
if iqn is not None:
if not is_valid_iqn(iqn):
raise ValueError('{0} is not a valid iSCSI/iSER IQN.'
.format(iqn))
body_values['iqn'] = iqn
if vpsa_chap_user is not None:
body_values['vpsachapuser'] = verify_field(vpsa_chap_user,
"vpsa_chap_user")
if vpsa_chap_secret is not None:
body_values['vpsachapsecret'] = verify_field(vpsa_chap_secret,
"vpsa_chap_secret")
if host_chap_user is not None:
body_values['hostchapuser'] = verify_field(host_chap_user,
"host_chap_user")
if host_chap_secret is not None:
body_values['hostchapsecret'] = verify_field(host_chap_secret,
"host_chap_secret")
if ipsec_iscsi is not None:
body_values['ipsec_iscsi'] = verify_boolean(ipsec_iscsi, "ipsec_iscsi")
if ipsec_nfs is not None:
body_values['ipsec_nfs'] = verify_boolean(ipsec_nfs, "ipsec_nfs")
if not body_values:
raise ValueError('At least one of the following must be set: '
'"ip_address", "iqn", "vpsa_chap_user", '
'"vpsa_chap_secret", "host_chap_user", '
'"host_chap_secret", "ipsec_iscsi", "ipsec_nfs"')
body_values['force'] = verify_boolean(force, "force")
path = '/api/servers/{0}/config.json'.format(server_id)
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
