Python API

updated: 2021-04-17 00:43

Python API

In order to use the Python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so:

>>> from cinderclient import client
>>> cinder = client.Client('1', $OS_USER_NAME, $OS_PASSWORD, $OS_TENANT_NAME, $OS_AUTH_URL)
>>> cinder.volumes.list()
[]
>>> myvol = cinder.volumes.create(display_name="test-vol", size=1)
>>> myvol.id
ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70
>>> cinder.volumes.list()
[<Volume: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>]
>>>myvol.delete

Alternatively, you can create a client instance using the keystoneauth session API:

>>> from keystoneauth1 import loading
>>> from keystoneauth1 import session
>>> from cinderclient import client
>>> loader = loading.get_plugin_loader('password')
>>> auth = loader.load_from_options(auth_url=AUTH_URL,
...                                 username=USERNAME,
...                                 password=PASSWORD,
...                                 project_id=PROJECT_ID,
...                                 user_domain_name=USER_DOMAIN_NAME)
>>> sess = session.Session(auth=auth)
>>> cinder = client.Client(VERSION, session=sess)
>>> cinder.volumes.list()
[]

User Guides

In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (--os-username, --os-password, --os-tenant-id, and --os-auth-url) or set them in environment variables:

export OS_USERNAME=user
export OS_PASSWORD=pass
export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
export OS_AUTH_URL=http://auth.example.com:5000/v2.0

Once you’ve configured your authentication parameters, you can run cinder help to see a complete listing of available commands.

See also cinder CLI man page for detailed documentation.

Release Notes

All python-cinderclient release notes can now be found on the release notes page.

The following are kept for historical purposes.

1.4.0

  • Improved error reporting on reaching quota.
  • Volume status management for volume migration.
  • Added command to fetch specified backend capabilities.
  • Added commands for modifying image metadata.
  • Support for non-disruptive backup.
  • Support for cloning consistency groups.

1.3.1

  • Fixed usage of the –debug option.
  • Documentation and API example improvements.
  • Set max volume size limit for the tenant.
  • Added encryption-type-update to cinderclient.
  • Added volume multi attach support.
  • Support host-attach of volumes.

1.3.0

  • Revert version discovery support due to this breaking deployments using proxies. We will revisit this once the Kilo config option ‘public_endpoint’ has been available longer to allow these deployments to work again with version discovery available from the Cinder client.
  • Add volume multi-attach support.
  • Add encryption-type-update to update volume encryption types.

1.2.2

  • IMPORTANT: version discovery breaks deployments using proxies and has been reverted in v1.3.0 . Do not use this version.
  • Update requirements to resolve conflicts with other OpenStack projects

1.2.1

  • IMPORTANT: version discovery breaks deployments using proxies and has been reverted in v1.3.0 . Do not use this version.
  • Remove warnings about Keystone unable to contact endpoint for discovery.
  • backup-create subcommand allows specifying –incremental to do an incremental backup.
  • Modify consistency groups using the consisgroup-update subcommand. Change the name, description, add volumes, or remove volumes.
  • Create consistency group from consistency group snapshot using the consisgroup-create-from-src subcommand.
  • –force no longer needs a boolean to be specified.

1.2.0

  • IMPORTANT: version discovery breaks deployments using proxies and has been reverted in v1.3.0 . Do not use this version.
  • Add metadata during snapshot create.
  • Add TTY password entry when no password is environment vars or –os-password.
  • Ability to set backup quota in quota-update subcommand.
  • Force the client to use a particular Cinder API endpoint with –bypass-url.
  • Create a volume from an image by image name.
  • New type-default subcommand will display the default volume type.
  • New type-update subcommand allows updating a volume type’s description.
  • type-list subcommand displays volume type description.
  • type-create subcommand allows setting the description.
  • Show pools to a backend when doing a service-list subcommand.
  • List and update consistency group quotas.
  • Create volume types that are non-public and have particular project access.
  • -d is available as a shorter option to –debug.
  • transfer-list subcommand has an option for –all-tenants.
  • –sort option available instead of –sort-key and –sort-dir. E.q. –sort <key>[:<direction>].
  • Volume type name can now be updated via subcommand type-update.
  • bash completion gives subcommands when using ‘cinder help’.
  • Version discovery is now available. You no longer need a volumev2 service type in your keystone catalog.
  • Filter by tenant in list subcommand.

** Python 2.4 support removed.

** –sort-key and –sort-dir are deprecated. Use –sort instead.

** A dash will be displayed of None when there is no data to display under
a column.

1.1.1

1.1.0

  • Add support for ConsistencyGroups
  • Use Adapter from keystoneclient
  • Add support for Replication feature
  • Add pagination for Volume List

** Note Connection refused –> Connection error commit: c9e7818f3f90ce761ad8ccd09181c705880a4266 ** Note Mask Passwords in log output commit: 80582f2b860b2dadef7ae07bdbd8395bf03848b1

1.0.9

1.0.8

  • Add support for reset-state on multiple volumes or snapshots at once
  • Add volume retype command

1.0.7

  • Add support for read-only volumes
  • Add support for setting snapshot metadata
  • Deprecate volume-id arg to backup restore in favor of –volume
  • Add quota-usage command
  • Fix exception deprecation warning message
  • Report error when no args supplied to rename cmd

1.0.6

  • Add support for multiple endpoints
  • Add response info for backup command
  • Add metadata option to cinder list command
  • Add timeout parameter for requests
  • Add update action for snapshot metadata
  • Add encryption metadata support
  • Add volume migrate support
  • Add support for QoS specs

1.0.5

  • Add CLI man page
  • Add Availability Zone list command
  • Add support for scheduler-hints
  • Add support to extend volumes
  • Add support to reset state on volumes and snapshots
  • Add snapshot support for quota class

1.0.4

  • Added support for backup-service commands

1.0.3

  • Added support for V2 Cinder API
  • Corrected upload-volume-to-image help messaging
  • Align handling of metadata args for all methods
  • Update OSLO version
  • Correct parsing of volume metadata
  • Enable force delete of volumes and snapshots in error state
  • Implement clone volume API call
  • Add list-extensions call to cinderclient
  • Add bootable column to list output
  • Add retries to cinderclient operations
  • Add Type/Extra-Specs support
  • Add volume and snapshot rename commands
updated: 2021-04-17 00:43
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?