Block Storage API

For details on how to use block_storage, see Using OpenStack Block Storage

The BlockStorage Class

The block_storage high-level interface is available through the block_storage member of a Connection object. The block_storage member will only be added if the service is detected.

Volume Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_volume(volume)

Get a single volume

Parameters

volume – The value can be the ID of a volume or a Volume instance.

Returns

One Volume

Raises

ResourceNotFound when no resource can be found.

find_volume(name_or_id, ignore_missing=True, *, details=True, all_projects=False)

Find a single volume

Parameters
  • snapshot – The name or ID a volume

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the volume does not exist.

  • details (bool) – When set to False no extended attributes will be returned. The default, True, will cause objects with additional attributes to be returned.

  • all_projects (bool) – When set to True, search for volume by name across all projects. Note that this will likely result in a higher chance of duplicates. Admin-only by default.

Returns

One Volume

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

volumes(*, details=True, all_projects=False, **query)

Retrieve a generator of volumes

Parameters
  • details (bool) – When set to False no extended attributes will be returned. The default, True, will cause objects with additional attributes to be returned.

  • all_projects (bool) – When set to True, list volumes from all projects. Admin-only by default.

  • query (kwargs) –

    Optional query parameters to be sent to limit the volumes being returned. Available parameters include:

    • name: Name of the volume as a string.

    • status: Value of the status of the volume so that you can filter on “available” for example.

Returns

A generator of volume objects.

create_volume(**attrs)

Create a new volume from attributes

Parameters

attrs (dict) – Keyword arguments which will be used to create a Volume, comprised of the properties on the Volume class.

Returns

The results of volume creation

Return type

Volume

delete_volume(volume, ignore_missing=True, force=False)

Delete a volume

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the volume does not exist. When set to True, no exception will be set when attempting to delete a nonexistent volume.

  • force (bool) – Whether to try forcing volume deletion.

Returns

None

update_volume(volume, **attrs)

Update a volume

Parameters
  • volume – Either the ID of a volume or a Volume instance.

  • attrs (dict) – The attributes to update on the volume.

Returns

The updated volume

Return type

Volume

get_volume_metadata(volume)

Return a dictionary of metadata for a volume

Parameters

volume – Either the ID of a volume or a Volume.

Returns

A Volume with the volume’s metadata. All keys and values are Unicode text.

Return type

Volume

set_volume_metadata(volume, **metadata)

Update metadata for a volume

Parameters
  • volume – Either the ID of a volume or a Volume.

  • metadata (kwargs) – Key/value pairs to be updated in the volume’s metadata. No other metadata is modified by this call. All keys and values are stored as Unicode.

Returns

A Volume with the volume’s metadata. All keys and values are Unicode text.

Return type

Volume

delete_volume_metadata(volume, keys=None)

Delete metadata for a volume

Parameters
  • volume – Either the ID of a volume or a Volume.

  • keys (list) – The keys to delete. If left empty complete metadata will be removed.

Return type

None

extend_volume(volume, size)

Extend a volume

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • size – New volume size

Returns

None

set_volume_readonly(volume, readonly=True)

Set a volume’s read-only flag.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • readonly (bool) – Whether the volume should be a read-only volume or not.

Returns

None

retype_volume(volume, new_type, migration_policy='never')

Retype the volume.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • new_type (str) – The new volume type that volume is changed with.

  • migration_policy (str) – Specify if the volume should be migrated when it is re-typed. Possible values are on-demand or never. Default: never.

Returns

None

set_volume_bootable_status(volume, bootable)

Set bootable status of the volume.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • bootable (bool) – Specifies whether the volume should be bootable or not.

Returns

None

reset_volume_status(volume, status, attach_status, migration_status)

Reset volume statuses.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • status (str) – The new volume status.

  • attach_status (str) – The new volume attach status.

  • migration_status (str) – The new volume migration status (admin only).

Returns

None

revert_volume_to_snapshot(volume, snapshot)

Revert a volume to its latest snapshot.

This method only support reverting a detached volume, and the volume status must be available.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • snapshot – The value can be either the ID of a snapshot or a Snapshot instance.

Returns

None

attach_volume(volume, mountpoint, instance=None, host_name=None)

Attaches a volume to a server.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • mountpoint (str) – The attaching mount point.

  • instance (str) – The UUID of the attaching instance.

  • host_name (str) – The name of the attaching host.

Returns

None

detach_volume(volume, attachment, force=False, connector=None)

Detaches a volume from a server.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • attachment (str) – The ID of the attachment.

  • force (bool) – Whether to force volume detach (Rolls back an unsuccessful detach operation after you disconnect the volume.)

  • connector (dict) – The connector object.

Returns

None

unmanage_volume(volume)
Removes a volume from Block Storage management without removing the

back-end storage object that is associated with it.

Parameters

volume – The value can be either the ID of a volume or a Volume instance.

Returns

None

migrate_volume(volume, host=None, force_host_copy=False, lock_volume=False, cluster=None)

Migrates a volume to the specified host.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • host (str) – The target host for the volume migration. Host format is host@backend.

  • force_host_copy (bool) – If false (the default), rely on the volume backend driver to perform the migration, which might be optimized. If true, or the volume driver fails to migrate the volume itself, a generic host-based migration is performed.

  • lock_volume (bool) – If true, migrating an available volume will change its status to maintenance preventing other operations from being performed on the volume such as attach, detach, retype, etc.

  • cluster (str) – The target cluster for the volume migration. Cluster format is cluster@backend. Starting with microversion 3.16, either cluster or host must be specified. If host is specified and is part of a cluster, the cluster is used as the target for the migration.

Returns

None

complete_volume_migration(volume, new_volume, error=False)

Complete the migration of a volume.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • new_volume (str) – The UUID of the new volume.

  • error (bool) – Used to indicate if an error has occured elsewhere that requires clean up.

Returns

None

upload_volume_to_image(volume, image_name, force=False, disk_format=None, container_format=None, visibility=None, protected=None)

Uploads the specified volume to image service.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • name (str image) – The name for the new image.

  • force (bool) – Enables or disables upload of a volume that is attached to an instance.

  • disk_format (str) – Disk format for the new image.

  • container_format (str) – Container format for the new image.

  • visibility (str) – The visibility property of the new image.

  • protected (str) – Whether the new image is protected.

Returns

dictionary describing the image.

reserve_volume(volume)

Mark volume as reserved.

Parameters

volume – The value can be either the ID of a volume or a Volume instance.

Returns

None

unreserve_volume(volume)

Unmark volume as reserved.

Parameters

volume – The value can be either the ID of a volume or a Volume instance.

Returns

None

begin_volume_detaching(volume)

Update volume status to ‘detaching’.

Parameters

volume – The value can be either the ID of a volume or a Volume instance.

Returns

None

abort_volume_detaching(volume)

Update volume status to ‘in-use’.

Parameters

volume – The value can be either the ID of a volume or a Volume instance.

Returns

None

init_volume_attachment(volume, connector)

Initialize volume attachment.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • connector (dict) – The connector object.

Returns

None

terminate_volume_attachment(volume, connector)

Update volume status to ‘in-use’.

Parameters
  • volume – The value can be either the ID of a volume or a Volume instance.

  • connector (dict) – The connector object.

Returns

None

Backend Pools Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
backend_pools(**query)

Returns a generator of cinder Back-end storage pools

Parameters

query (kwargs) – Optional query parameters to be sent to limit the resources being returned.

:returns A generator of cinder Back-end storage pools objects

Backup Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
backups(*, details=True, **query)

Retrieve a generator of backups

Parameters
  • details (bool) – When set to False no additional details will be returned. The default, True, will cause objects with additional attributes to be returned.

  • query (dict) –

    Optional query parameters to be sent to limit the resources being returned:

    • offset: pagination marker

    • limit: pagination limit

    • sort_key: Sorts by an attribute. A valid value is name, status, container_format, disk_format, size, id, created_at, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key attribute value.

    • sort_dir: Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is desc.

    • project_id: Project ID to query backups for.

Returns

A generator of backup objects.

get_backup(backup)

Get a backup

Parameters

backup – The value can be the ID of a backup or a Backup instance.

Returns

Backup instance

Return type

Backup

find_backup(name_or_id, ignore_missing=True, *, details=True)

Find a single backup

Parameters
  • snapshot – The name or ID a backup

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the backup does not exist.

  • details (bool) – When set to False no additional details will be returned. The default, True, will cause objects with additional attributes to be returned.

Returns

One Backup

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

create_backup(**attrs)

Create a new Backup from attributes with native API

Parameters

attrs (dict) – Keyword arguments which will be used to create a Backup comprised of the properties on the Backup class.

Returns

The results of Backup creation

Return type

Backup

delete_backup(backup, ignore_missing=True, force=False)

Delete a CloudBackup

Parameters
  • backup – The value can be the ID of a backup or a Backup instance

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the zone does not exist. When set to True, no exception will be set when attempting to delete a nonexistent zone.

  • force (bool) – Whether to try forcing backup deletion

Returns

None

restore_backup(backup, volume_id=None, name=None)

Restore a Backup to volume

Parameters
  • backup – The value can be the ID of a backup or a Backup instance

  • volume_id – The ID of the volume to restore the backup to.

  • name – The name for new volume creation to restore.

Returns

Updated backup instance

Return type

Backup

reset_backup(backup, status)

Reset status of the backup

Parameters
  • backup – The value can be either the ID of a backup or a Backup instance.

  • status (str) – New backup status

Returns

None

Availability Zone Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
availability_zones()

Return a generator of availability zones

Returns

A generator of availability zone

Return type

AvailabilityZone

Limits Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_limits()

Retrieves limits

Returns

A Limit object, including both AbsoluteLimit and RateLimit

Return type

Limit

Capabilities Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_capabilities(host)

Get a backend’s capabilites

Parameters

host – Specified backend to obtain volume stats and properties.

Returns

One :class: ~openstack.block_storage.v3.capabilites.Capabilities instance.

Raises

ResourceNotFound when no resource can be found.

Group Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_group(group_id, **attrs)

Get a group

Parameters
  • group_id – The ID of the group to get.

  • attrs (dict) – Optional query parameters to be sent to limit the resources being returned.

Returns

A Group instance.

Return type

group

find_group(name_or_id, ignore_missing=True, *, details=True)

Find a single group

Parameters
  • name_or_id – The name or ID of a group.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the group snapshot does not exist.

  • details (bool) – When set to False, no additional details will be returned. The default, True, will cause additional details to be returned.

Returns

One Group

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

groups(*, details=True, **query)

Retrieve a generator of groups

Parameters
  • details (bool) – When set to False, no additional details will be returned. The default, True, will cause additional details to be returned.

  • query (dict) –

    Optional query parameters to be sent to limit the resources being returned:

    • all_tenants: Shows details for all project.

    • sort: Comma-separated list of sort keys and optional sort directions.

    • limit: Returns a number of items up to the limit value.

    • offset: Used in conjunction with limit to return a slice of items. Specifies where to start in the list.

    • marker: The ID of the last-seen item.

    • list_volume: Show volume ids in this group.

    • detailed: If True, will list groups with details.

    • search_opts: Search options.

Returns

A generator of group objects.

create_group(**attrs)

Create a new group from attributes

Parameters

attrs (dict) – Keyword arguments which will be used to create a Group comprised of the properties on the Group class.

Returns

The results of group creation.

Return type

Group.

create_group_from_source(**attrs)

Creates a new group from source

Parameters

attrs (dict) – Keyword arguments which will be used to create a Group comprised of the properties on the Group class.

Returns

The results of group creation.

Return type

Group.

reset_group_state(group, status)

Reset group status

Parameters
  • group – The Group to set the state.

  • status – The status for a group.

Returns

None

delete_group(group, delete_volumes=False)

Delete a group

Parameters
  • group – The Group to delete.

  • delete_volumes (bool) – When set to True, volumes in group will be deleted.

Returns

None.

update_group(group, **attrs)

Update a group

Parameters
  • group – The value can be the ID of a group or a Group instance.

  • attrs (dict) – The attributes to update on the group.

Returns

The updated group

Return type

Group

Group Snapshot Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_group_snapshot(group_snapshot_id)

Get a group snapshot

Parameters

group_snapshot_id – The ID of the group snapshot to get.

Returns

A GroupSnapshot instance.

Return type

group_snapshot

find_group_snapshot(name_or_id, ignore_missing=True, *, details=True)

Find a single group snapshot

Parameters
  • name_or_id – The name or ID of a group snapshot.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the group snapshot does not exist.

  • details (bool) – When set to False, no additional details will be returned. The default, True, will cause additional details to be returned.

Returns

One group_snapshot

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

group_snapshots(*, details=True, **query)

Retrieve a generator of group snapshots

Parameters
  • details (bool) – When True, returns GroupSnapshot objects with additional attributes filled.

  • query (kwargs) – Optional query parameters to be sent to limit the group snapshots being returned.

Returns

A generator of group snapshtos.

create_group_snapshot(**attrs)

Create a group snapshot

Parameters

attrs (dict) – Keyword arguments which will be used to create a GroupSnapshot comprised of the properties on the GroupSnapshot class.

Returns

The results of group snapshot creation.

Return type

group_snapshot.

reset_group_snapshot_state(group_snapshot, state)

Reset group snapshot status

Parameters
  • group_snapshot – The GroupSnapshot to set the state.

  • state – The state of the group snapshot to be set.

Returns

None

delete_group_snapshot(group_snapshot, ignore_missing=True)

Delete a group snapshot

Parameters

group_snapshot – The GroupSnapshot to delete.

Returns

None

Group Type Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_group_type(group_type)

Get a specific group type

Parameters

group_type – The value can be the ID of a group type or a GroupType instance.

Returns

One :class: ~openstack.block_storage.v3.group_type.GroupType instance.

Raises

ResourceNotFound when no resource can be found.

find_group_type(name_or_id, ignore_missing=True)

Find a single group type

Parameters
  • name_or_id – The name or ID of a group type.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the group type does not exist.

Returns

One GroupType

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

group_types(**query)

Retrive a generator of group types

Parameters

query (dict) –

Optional query parameters to be sent to limit the resources being returned:

  • sort: Comma-separated list of sort keys and optional sort directions in the form of <key> [:<direction>]. A valid direction is asc (ascending) or desc (descending).

  • limit: Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

  • offset: Used in conjunction with limit to return a slice of items. Is where to start in the list.

  • marker: The ID of the last-seen item.

Returns

A generator of group type objects.

create_group_type(**attrs)

Create a group type

Parameters

attrs (dict) – Keyword arguments which will be used to create a GroupType comprised of the properties on the GroupType class.

Returns

The results of group type creation.

Return type

GroupTye.

delete_group_type(group_type, ignore_missing=True)

Delete a group type

Parameters
  • group_type – The value can be the ID of a group type or a GroupType instance.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the zone does not exist. When set to True, no exception will be set when attempting to delete a nonexistent zone.

Returns

None

update_group_type(group_type, **attrs)

Update a group_type

Parameters
  • group_type – The value can be the ID of a group type or a GroupType instance.

  • attrs (dict) – The attributes to update on the group type.

Returns

The updated group type.

Return type

GroupType

fetch_group_type_group_specs(group_type)

Lists group specs of a group type.

Parameters

group_type – Either the ID of a group type or a GroupType instance.

Returns

One GroupType

create_group_type_group_specs(group_type, group_specs)

Create group specs for a group type.

Parameters
  • group_type – Either the ID of a group type or a GroupType instance.

  • group_specs (dict) – dict of extra specs

Returns

One GroupType

get_group_type_group_specs_property(group_type, prop)

Retrieve a group spec property for a group type.

Parameters
  • group_type – Either the ID of a group type or a GroupType instance.

  • prop (str) – Property name.

Returns

String value of the requested property.

update_group_type_group_specs_property(group_type, prop, val)

Update a group spec property for a group type.

Parameters
  • group_type – Either the ID of a group type or a GroupType instance.

  • prop (str) – Property name.

  • val (str) – Property value.

Returns

String value of the requested property.

delete_group_type_group_specs_property(group_type, prop)

Delete a group spec property from a group type.

Parameters
  • group_type – Either the ID of a group type or a GroupType instance.

  • prop (str) – Property name.

Returns

None

Type Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_type(type)

Get a single type

Parameters

type – The value can be the ID of a type or a Type instance.

Returns

One Type

Raises

ResourceNotFound when no resource can be found.

find_type(name_or_id, ignore_missing=True)

Find a single volume type

Parameters
  • snapshot – The name or ID a volume type

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the volume type does not exist.

Returns

One Type

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

types(**query)

Retrieve a generator of volume types

Returns

A generator of volume type objects.

create_type(**attrs)

Create a new type from attributes

Parameters

attrs (dict) – Keyword arguments which will be used to create a Type, comprised of the properties on the Type class.

Returns

The results of type creation

Return type

Type

delete_type(type, ignore_missing=True)

Delete a type

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the type does not exist. When set to True, no exception will be set when attempting to delete a nonexistent type.

Returns

None

update_type(type, **attrs)

Update a type

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • attrs (dict) – The attributes to update on the type

Returns

The updated type

Return type

Type

update_type_extra_specs(type, **attrs)

Update the extra_specs for a type

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • attrs (dict) – The extra spec attributes to update on the type

Returns

A dict containing updated extra_specs

delete_type_extra_specs(type, keys)

Delete the extra_specs for a type

Note: This method will do a HTTP DELETE request for every key in keys.

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • keys – The keys to delete

Returns

None

get_type_access(type)

Lists project IDs that have access to private volume type.

Parameters

type – The value can be either the ID of a type or a Type instance.

Returns

List of dictionaries describing projects that have access to the specified type

add_type_access(type, project_id)

Adds private volume type access to a project.

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • project_id (str) – The ID of the project. Volume Type access to be added to this project ID.

Returns

None

remove_type_access(type, project_id)

Remove private volume type access from a project.

Parameters
  • type – The value can be either the ID of a type or a Type instance.

  • project_id (str) – The ID of the project. Volume Type access to be removed to this project ID.

Returns

None

get_type_encryption(volume_type_id)

Get the encryption details of a volume type

Parameters

volume_type_id – The value can be the ID of a type or a Type instance.

Returns

One TypeEncryption

Raises

ResourceNotFound when no resource can be found.

create_type_encryption(volume_type, **attrs)

Create new type encryption from attributes

Parameters
  • volume_type – The value can be the ID of a type or a Type instance.

  • attrs (dict) – Keyword arguments which will be used to create a TypeEncryption, comprised of the properties on the TypeEncryption class.

Returns

The results of type encryption creation

Return type

TypeEncryption

delete_type_encryption(encryption=None, volume_type=None, ignore_missing=True)

Delete type encryption attributes

Parameters
  • encryption – The value can be None or a TypeEncryption instance. If encryption_id is None then volume_type_id must be specified.

  • volume_type – The value can be the ID of a type or a Type instance. Required if encryption_id is None.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the type does not exist. When set to True, no exception will be set when attempting to delete a nonexistent type.

Returns

None

update_type_encryption(encryption=None, volume_type=None, **attrs)

Update a type

Parameters
  • encryption – The value can be None or a TypeEncryption instance. If this is None then volume_type_id must be specified.

  • volume_type – The value can be the ID of a type or a Type instance. Required if encryption_id is None.

  • attrs (dict) – The attributes to update on the type encryption.

Returns

The updated type encryption

Return type

TypeEncryption

Snapshot Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_snapshot(snapshot)

Get a single snapshot

Parameters

snapshot – The value can be the ID of a snapshot or a Snapshot instance.

Returns

One Snapshot

Raises

ResourceNotFound when no resource can be found.

find_snapshot(name_or_id, ignore_missing=True, *, details=True, all_projects=False)

Find a single snapshot

Parameters
  • snapshot – The name or ID a snapshot

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the snapshot does not exist. When set to True, None will be returned when attempting to find a nonexistent resource.

  • details (bool) – When set to False :class: ~openstack.block_storage.v3.snapshot.Snapshot objects will be returned. The default, True, will cause more attributes to be returned.

  • all_projects (bool) – When set to True, search for snapshot by name across all projects. Note that this will likely result in a higher chance of duplicates. Admin-only by default.

Returns

One Snapshot

Raises

ResourceNotFound when no resource can be found.

Raises

DuplicateResource when multiple resources are found.

snapshots(*, details=True, all_projects=False, **query)

Retrieve a generator of snapshots

Parameters
  • details (bool) – When set to False :class: ~openstack.block_storage.v3.snapshot.Snapshot objects will be returned. The default, True, will cause more attributes to be returned.

  • all_projects (bool) – When set to True, list snapshots from all projects. Admin-only by default.

  • query (kwargs) –

    Optional query parameters to be sent to limit the snapshots being returned. Available parameters include:

    • name: Name of the snapshot as a string.

    • project_id: Filter the snapshots by project.

    • volume_id: volume id of a snapshot.

    • status: Value of the status of the snapshot so that you can filter on “available” for example.

Returns

A generator of snapshot objects.

create_snapshot(**attrs)

Create a new snapshot from attributes

Parameters

attrs (dict) – Keyword arguments which will be used to create a Snapshot, comprised of the properties on the Snapshot class.

Returns

The results of snapshot creation

Return type

Snapshot

update_snapshot(snapshot, **attrs)

Update a snapshot

Parameters
  • snapshot – Either the ID of a snapshot or a Snapshot instance.

  • attrs (dict) – The attributes to update on the snapshot.

Returns

The updated snapshot

Return type

Snapshot

delete_snapshot(snapshot, ignore_missing=True, force=False)

Delete a snapshot

Parameters
  • snapshot – The value can be either the ID of a snapshot or a Snapshot instance.

  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the snapshot does not exist. When set to True, no exception will be set when attempting to delete a nonexistent snapshot.

  • force (bool) – Whether to try forcing snapshot deletion.

Returns

None

get_snapshot_metadata(snapshot)

Return a dictionary of metadata for a snapshot

Parameters

snapshot – Either the ID of a snapshot or a Snapshot.

Returns

A Snapshot with the snapshot’s metadata. All keys and values are Unicode text.

Return type

Snapshot

set_snapshot_metadata(snapshot, **metadata)

Update metadata for a snapshot

Parameters
  • snapshot – Either the ID of a snapshot or a Snapshot.

  • metadata (kwargs) – Key/value pairs to be updated in the snapshot’s metadata. No other metadata is modified by this call. All keys and values are stored as Unicode.

Returns

A Snapshot with the snapshot’s metadata. All keys and values are Unicode text.

Return type

Snapshot

delete_snapshot_metadata(snapshot, keys=None)

Delete metadata for a snapshot

Parameters
  • snapshot – Either the ID of a snapshot or a Snapshot.

  • keys (list) – The keys to delete. If left empty complete metadata will be removed.

Return type

None

reset_snapshot(snapshot, status)

Reset status of the snapshot

Parameters
  • snapshot – The value can be either the ID of a backup or a Snapshot instance.

  • status (str) – New snapshot status

Returns

None

set_snapshot_status(snapshot, status, progress=None)

Update fields related to the status of a snapshot.

Parameters
  • snapshot – The value can be either the ID of a backup or a Snapshot instance.

  • status (str) – New snapshot status

  • progress (str) – A percentage value for snapshot build progress.

Returns

None

Stats Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
backend_pools(**query)

Returns a generator of cinder Back-end storage pools

Parameters

query (kwargs) – Optional query parameters to be sent to limit the resources being returned.

:returns A generator of cinder Back-end storage pools objects

QuotaSet Operations

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
get_quota_set(project, usage=False, **query)

Show QuotaSet information for the project

Parameters
  • project – ID or instance of Project of the project for which the quota should be retrieved

  • usage (bool) – When set to True quota usage and reservations would be filled.

  • query (dict) – Additional query parameters to use.

Returns

One QuotaSet

Raises

ResourceNotFound when no resource can be found.

get_quota_set_defaults(project)

Show QuotaSet defaults for the project

Parameters

project – ID or instance of Project of the project for which the quota should be retrieved

Returns

One QuotaSet

Raises

ResourceNotFound when no resource can be found.

revert_quota_set(project, **query)

Reset Quota for the project/user.

Parameters
  • project – ID or instance of Project of the project for which the quota should be resetted.

  • query (dict) – Additional parameters to be used.

Returns

None

update_quota_set(quota_set, query=None, **attrs)

Update a QuotaSet.

Parameters
  • quota_set – Either the ID of a quota_set or a QuotaSet instance.

  • query (dict) – Optional parameters to be used with update call.

  • attrs – The attributes to update on the QuotaSet represented by quota_set.

Returns

The updated QuotaSet

Return type

QuotaSet

Helpers

class openstack.block_storage.v3._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
wait_for_status(res, status='available', failures=None, interval=2, wait=120)

Wait for a resource to be in a particular status.

Parameters
  • res – The resource to wait on to reach the specified status. The resource must have a status attribute.

  • status (str) – Desired status.

  • failures (list) – Statuses that would be interpreted as failures.

  • interval – Number of seconds to wait before to consecutive checks. Default to 2.

  • wait – Maximum number of seconds to wait before the change. Default to 120.

Returns

The resource is returned on success.

Raises

ResourceTimeout if transition to the desired status failed to occur in specified seconds.

Raises

ResourceFailure if the resource has transited to one of the failure statuses.

Raises

AttributeError if the resource does not have a status attribute.

wait_for_delete(res, interval=2, wait=120)

Wait for a resource to be deleted.

Parameters
  • res – The resource to wait on to be deleted.

  • interval (int) – Number of seconds to wait before two consecutive checks. Default to 2.

  • wait (int) – Maximum number of seconds to wait before the change. Default to 120.

Returns

The resource is returned on success.

Raises

ResourceTimeout if transition to delete failed to occur in the specified seconds.