def get_pool(session, pool_id, return_type=None, **kwargs):
"""
Retrieves details for all single storage 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 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)
path = '/api/pools/{0}.json'.format(pool_id)
return session.get_api(path=path, return_type=return_type, **kwargs)
def migrate_zcs_image_repository(session, pool_id, return_type=None, **kwargs):
"""
Migrates the ZCS image repository from the existing pool to the specified
pool. 100 GB will be freed from the existing pool and consumed on the
specified pool for this repository.
: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 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)
body_values = {'pool': pool_id}
path = '/api/settings/migrate_images_repository.json'
return session.post_api(path=path, body=body_values,
return_type=return_type, **kwargs)
def cancel_pool_shrink(session,
pool_id,
raid_group_id,
return_type=None,
**kwargs):
"""
Shrink 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 raid_group_id: str
:param raid_group_id: RAID Group 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.
"""
verify_pool_id(pool_id=pool_id)
verify_raid_groups(raid_groups=raid_group_id)
path = "/api/pools/{0}/cancel_shrink.json".format(raid_group_id)
return session.post_api(path=path, 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 rename_pool(session, pool_id, display_name, return_type=None, **kwargs):
"""
Sets the "display_name" pool parameter to a new value.
: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 display_name: str
:param display_name: The new "display_name" to set. May not contain a
single quote (') character. 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)
display_name = verify_field(display_name, "display_name")
body_values = {'new_name': display_name}
path = '/api/pools/{0}/rename.json'.format(pool_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def delete_pool(session, pool_id, return_type=None, **kwargs):
"""
Deletes a storage pool. The storage pool must not contain any volumes,
including in the pool's recycle bin. This action is irreversible.
: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 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)
path = '/api/pools/{0}.json'.format(pool_id)
return session.delete_api(path=path, return_type=return_type, **kwargs)
def disable_cache(session, pool_id, return_type=None, **kwargs):
verify_pool_id(pool_id)
path = '/api/pools/{0}'.format(pool_id)
body_values = {'command': 'enable'}
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 add_raid_groups_to_pool(session,
pool_id,
raid_groups,
capacity,
return_type=None,
**kwargs):
"""
Adds RAID groups to a storage pool. RAID groups need to be of the same
type as the RAID groups already participating in the pool. RAID groups
also must not be allocated to another 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 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-3,RaidGroup-4'. Required.
:type capacity: int
:param capacity: The total capacity in GB that will be added for the
storage pool. May not exceed the capacity of the combined added
RAID groups. 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)
verify_raid_groups(raid_groups)
capacity = verify_capacity(capacity, "Storage pool")
body_values = {
'raid_groups': raid_groups,
'capacity': '{0}G'.format(capacity)
}
path = '/api/pools/{0}/expand.json'.format(pool_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def expand_pool(session,
pool_id,
raid_groups_ids,
capacity,
return_type=None,
**kwargs):
"""
Add additional RAID Groups to 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 raid_groups_ids: str
:param raid_groups_ids: RAID Group IDs separated by comma ,
:type capacity: int
:param capacity: Capacity in GB. 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=pool_id)
verify_raid_groups(raid_groups=raid_groups_ids)
path = "/api/pools/{0}/expand.json".format(pool_id)
body_values = {
"capacity": "{}G".format(capacity),
"raid_groups": raid_groups_ids
}
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)
def get_volumes_in_pool_recycle_bin(session,
pool_id,
start=None,
limit=None,
return_type=None,
**kwargs):
"""
Retrieves a list of volumes in the pool's recycle bin.
: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 start: int
:param start: The offset to start displaying volumes from. Optional.
:type: limit: int
:param limit: The maximum number of volumes to return. 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_pool_id(pool_id)
parameters = verify_start_limit(start, limit)
path = '/api/pools/{0}/volumes_in_recycle_bin.json'.format(pool_id)
return session.get_api(path=path,
parameters=parameters,
return_type=return_type,
**kwargs)
def get_pool_performance(session,
pool_id,
interval=1,
return_type=None,
**kwargs):
"""
Retrieves metering statistics for the pool for the specified interval.
Default interval is one second.
: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 interval: int
:param interval: The interval to collect statistics for, in seconds.
: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)
interval = verify_positive_argument(interval, "interval")
path = '/api/pools/{0}/performance.json'.format(pool_id)
parameters = {'interval': interval}
return session.get_api(path=path,
parameters=parameters,
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 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 update_protection(session,
pool_id,
alertmode=None,
effectivecapacityhistory=None,
capacityhistory=None,
protectedmode=None,
effectiveprotectedmode=None,
emergencymode=None,
effectiveemergencymode=None,
return_type=None,
**kwargs):
"""
Update free capacity alert notification settings 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 capacityhistory: str
:param capacityhistory: Window size in minutes which is used to calculate
the rate of which free Pool capacity is consumed. This rate is used to
calculate the estimated time until a Pool is full.
:type effectivecapacityhistory: str
:param effectivecapacityhistory: Window size in minutes which is used to
calculate the rate of which free Pool effective capacity is consumed.
This rate is used to calculate the estimated time until a Pool is full.
:type effectiveprotectedmode: str
:param effectiveprotectedmode: Block Volume/Share/Pool creation when it's
estimated that the Pool effective capacity will be full in this many
minutes.
:type effectiveemergencymode: str
:param effectiveemergencymode: Delete snapshots, starting with the oldest,
when the Pool effective capacity has less than this number of GB left.
:type alertmode: int
:param alertmode: Send an alert when it is estimated that the Pool will be
at full capacity in this many minutes.
:type emergencymode: int
:param emergencymode: Delete snapshots, starting with the oldest, when the
Volume has less than this number of GB left.
:type capacityhistory: int
:param capacityhistory: Window size in minutes which is used to calculate
the rate of which free Volume capacity is consumed. This rate is used to
calculate the estimated time until a Volume is full
: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)
body = {}
if alertmode is not None:
body["alertmode"] = alertmode
if emergencymode is not None:
body['emergencymode'] = emergencymode
if effectiveemergencymode is not None:
body['effectiveemergencymode'] = effectiveemergencymode
if protectedmode is not None:
body['protectedmode'] = protectedmode
if effectiveprotectedmode is not None:
body['effectiveprotectedmode'] = effectiveprotectedmode
if capacityhistory is not None:
body['capacityhistory'] = capacityhistory
if effectivecapacityhistory is not None:
body['effectivecapacityhistory'] = effectivecapacityhistory
if not body:
raise ValueError('At least one of the following must be set: '
'"alertmode", "emergencymode", '
'"effectiveemergencymode", '
'"protectedmode", "effectiveprotectedmode", '
'"capacityhistory", "effectivecapacityhistory"')
path = "/api/pools/{0}/update_protection.json".format(pool_id)
return session.post_api(path=path,
body=body,
return_type=return_type,
**kwargs)
def update_pool_capacity_alerts(session,
pool_id,
capacityhistory=None,
alertmode=None,
protectedmode=None,
emergencymode=None,
return_type=None,
**kwargs):
"""
Update the pool alerting thresholds. Alerts are used both to notify
administrators of pending pool space exhaustion, as well as deleting
the oldest snapshots in an attempt to free space. 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 pool_id: str
:param pool_id: The pool 'name' value as returned by get_all_pools. For
example: 'pool-00000001'. Required.
:type capacityhistory: int
:param capacityhistory: The number of minutes used to calculate pool
exhaustion. This value is used in conjunction with "alertmode". For
example, if "capacityhistory" is 60 minutes, the VPSA will use the
amount of data written in the last 60 minutes to calculate the write
rate for the "alertmode" value. Optional.
:type alertmode: int
:param alertmode: The number of minutes before the storage pool is
predicted to reach space exhaustion. Works in conjunction with the
"capacityhistory" value. If the VPSA predicts the pool will run out
of space in less than or equal to the amount of minutes defined here,
an alert will be sent to the VPSA administrator. Optional.
:type protectedmode: int
:param protectedmode: If the number of minutes before the pool is
predicted to reach space exhaustion is less than this value, the VPSA
will not allow the creation of new volumes, shares, or snapshots.
Optional.
:type emergencymode: int
:param emergencymode: If the number of GB free on the pool is less than
this value, the VPSA will start deleting old snapshots in an attempt
to prevent space exhaustion. 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_pool_id(pool_id)
capacityhistory = verify_positive_argument(capacityhistory,
"capacityhistory")
alertmode = verify_positive_argument(alertmode, "alertmode")
protectedmode = verify_positive_argument(protectedmode, "protectedmode")
emergencymode = verify_positive_argument(emergencymode, "emergencymode")
body_values = {}
if capacityhistory is not None:
body_values['capacityhistory'] = capacityhistory
if alertmode is not None:
body_values['alertmode'] = alertmode
if protectedmode is not None:
body_values['protectedmode'] = protectedmode
if emergencymode is not None:
body_values['emergencymode'] = emergencymode
if not body_values:
raise ValueError('At least one of the following must be set: '
'"capacityhistory", "alertmode", "protectedmode", '
'"emergencymode"')
path = '/api/pools/{0}/update_protection.json'.format(pool_id)
return session.post_api(path=path,
body=body_values,
return_type=return_type,
**kwargs)