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

manage_volume(**attrs)
Creates a volume by using existing storage rather than

allocating new storage.

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

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:

Dictionary containing the modified connector object

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(project=None)

Retrieves limits

Parameters:

project – A project to get limits for. The value can be either the ID of a project or an Project instance.

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

Service 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)
find_service(name_or_id, ignore_missing=True, **query)

Find a single service

Parameters:
  • name_or_id – The name or ID of a service

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

  • query (dict) – Additional attributes like ‘host’

Returns:

One: class:~openstack.block_storage.v3.service.Service or None

Raises:

ResourceNotFound when no resource can be found.

Raises:

DuplicateResource when multiple resources are found.

services(**query)

Return a generator of service

Parameters:

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

Returns:

A generator of Service objects

Return type:

class: ~openstack.block_storage.v3.service.Service

enable_service(service)

Enable a service

Parameters:

service – Either the ID of a service or a Service instance.

Returns:

Updated service instance

Return type:

class: ~openstack.block_storage.v3.service.Service

disable_service(service, *, reason=None)

Disable a service

Parameters:
  • service – Either the ID of a service or a Service instance

  • reason (str) – The reason to disable a service

Returns:

Updated service instance

Return type:

class: ~openstack.block_storage.v3.service.Service

thaw_service(service)

Thaw a service

Parameters:

service – Either the ID of a service or a Service instance

Returns:

Updated service instance

Return type:

class: ~openstack.block_storage.v3.service.Service

freeze_service(service)

Freeze a service

Parameters:

service – Either the ID of a service or a Service instance

Returns:

Updated service instance

Return type:

class: ~openstack.block_storage.v3.service.Service

failover_service(service, *, cluster=None, backend_id=None)

Failover a service

Only applies to replicating cinder-volume services.

Parameters:

service – Either the ID of a service or a Service instance

Returns:

Updated service instance

Return type:

class: ~openstack.block_storage.v3.service.Service

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

manage_snapshot(**attrs)

Creates a snapshot by using existing storage rather than allocating new storage.

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

unmanage_snapshot(snapshot)

Unmanage a snapshot from block storage provisioning.

Parameters:

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

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, callback=None)

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.

  • callback – A callback function. This will be called with a single value, progress.

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, callback=None)

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.

  • callback – A callback function. This will be called with a single value, progress.

Returns:

The resource is returned on success.

Raises:

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

BlockStorageSummary 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)
summary(all_projects)

Get Volumes Summary

This method returns the volumes summary in the deployment.

Parameters:

all_projects – Whether to return the summary of all projects or not.

Returns:

One :class: ~openstack.block_storage.v3.block_storage_summary.Summary instance.

Attachments

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)
create_attachment(volume, **attrs)

Create a new attachment

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

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

  • attrs (dict) – Keyword arguments which will be used to create a Attachment comprised of the properties on the Attachment class like connector, instance_id, mode etc.

Returns:

The results of attachment creation

Return type:

Attachment

get_attachment(attachment)

Get a single volume

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

Parameters:

attachment – The value can be the ID of an attachment or a Attachment instance.

Returns:

One Attachment

Raises:

ResourceNotFound when no resource can be found.

attachments(**query)

Returns a generator of attachments.

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

Parameters:

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

Returns:

A generator of attachment objects.

delete_attachment(attachment, ignore_missing=True)

Delete an attachment

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

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

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

Returns:

None

update_attachment(attachment, **attrs)

Update an attachment

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

Parameters:
  • attachment – The value can be the ID of an attachment or a Attachment instance.

  • attrs (dict) – Keyword arguments which will be used to update a Attachment comprised of the properties on the Attachment class

Returns:

The updated attachment

Return type:

Attachment

complete_attachment(attachment)

Complete an attachment

This is an internal API and should only be called by services consuming volume attachments like nova, glance, ironic etc.

Parameters:

attachment – The value can be the ID of an attachment or a Attachment instance.

Returns:

None

Return type:

Attachment

Transfer 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)
create_transfer(**attrs)

Create a new Transfer record

Parameters:
  • volume_id – The value is ID of the volume.

  • name – The value is name of the transfer

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

Returns:

The results of Transfer creation

Return type:

Transfer

delete_transfer(transfer, ignore_missing=True)

Delete a volume transfer

Parameters:
  • transfer – The value can be either the ID of a transfer or a Transfer` instance.

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

Returns:

None

find_transfer(name_or_id, ignore_missing=True)

Find a single transfer

Parameters:
  • name_or_id – The name or ID a transfer

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

Returns:

One Transfer

Raises:

ResourceNotFound when no resource can be found.

Raises:

DuplicateResource when multiple resources are found.

get_transfer(transfer)

Get a single transfer

Parameters:

transfer – The value can be the ID of a transfer or a Transfer instance.

Returns:

One Transfer

Raises:

ResourceNotFound when no resource can be found.

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

Retrieve a generator of transfers

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 transfers from all projects. Admin-only by default.

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

Returns:

A generator of transfer objects.

accept_transfer(transfer_id, auth_key)

Accept a Transfer

Parameters:
  • transfer_id – The value can be the ID of a transfer or a Transfer instance.

  • auth_key – The key to authenticate volume transfer.

Returns:

The results of Transfer creation

Return type:

Transfer