OpenStack Cinder API Client Library

9.9.0 · active · verified Mon Apr 13

python-cinderclient is the official Python client library for interacting with the OpenStack Block Storage (Cinder) API. It provides both a Python API (the `cinderclient` module) and a command-line interface (`cinder`). It aims to implement 100% of the OpenStack Cinder API. The library is actively maintained as part of the OpenStack ecosystem, with releases typically aligning with OpenStack's development cycle, alongside more frequent patch releases. The current version is 9.9.0.

Warnings

deprecated Cinder API v2 is officially deprecated. While `python-cinderclient` might still support it for backward compatibility, new development and existing deployments should migrate to Cinder API v3.
Fix: Always import `client` from `cinderclient.v3` (e.g., `from cinderclient.v3 import client`) and set `OS_VOLUME_API_VERSION=3` in your environment or client initialization.
gotcha Authentication relies heavily on environment variables (e.g., `OS_USERNAME`, `OS_PASSWORD`, `OS_AUTH_URL`, `OS_PROJECT_ID`/`OS_TENANT_NAME`, `OS_REGION_NAME`). Incorrectly setting these, or not providing them when expected, will lead to authentication failures.
Fix: Ensure all necessary `OS_` environment variables are correctly set or explicitly passed during client initialization. Using `keystoneauth1.loading.get_plugin_loader('password').load_from_options` helps manage these.
deprecated The `--endpoint-type` CLI option has been deprecated. Users should utilize `--os-endpoint-type` instead when interacting via the command line.
Fix: When using the `cinder` CLI, replace `--endpoint-type` with `--os-endpoint-type`.
breaking Historically, there was a breaking change in versions 1.2.0 and 1.2.2 related to 'version discovery breaks deployments using proxies,' which was reverted in v1.3.0. This highlights potential issues with automatic version discovery and the importance of explicitly specifying API versions.
Fix: Always explicitly specify the Cinder API version (e.g., '3') during client initialization to avoid unexpected behavior, especially in complex network environments with proxies.

Install

pip install python-cinderclient PyPI

Imports

client
```
from cinderclient.v3 import client
```
Cinder API v3 is the current recommended version. Cinder API v1 and v2 are deprecated.

Quickstart

This quickstart demonstrates how to authenticate with OpenStack Keystone using `keystoneauth1` and then create a Cinder client to list volumes. It is recommended to set OpenStack credentials as environment variables (`OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_ID`/`OS_PROJECT_NAME`, `OS_REGION_NAME`, `OS_VOLUME_API_VERSION`) for security and ease of use. The client is initialized for Cinder API v3, which is the recommended version.

import os
from keystoneauth1 import loading
from keystoneauth1 import session
from cinderclient.v3 import client as cinder_client

# Set environment variables or replace with actual values
OS_AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
OS_USERNAME = os.environ.get('OS_USERNAME', 'admin')
OS_PASSWORD = os.environ.get('OS_PASSWORD', 'password')
OS_PROJECT_ID = os.environ.get('OS_PROJECT_ID', 'project_id') # Or OS_PROJECT_NAME
OS_REGION_NAME = os.environ.get('OS_REGION_NAME', 'RegionOne')
OS_VOLUME_API_VERSION = os.environ.get('OS_VOLUME_API_VERSION', '3')

# Load the authentication plugin
loader = loading.get_plugin_loader('password')
auth = loader.load_from_options(
    auth_url=OS_AUTH_URL,
    username=OS_USERNAME,
    password=OS_PASSWORD,
    project_id=OS_PROJECT_ID, # Use project_id or project_name
    user_domain_name='Default', # Often 'Default' for typical OpenStack setups
    project_domain_name='Default'
)

# Create a session
sess = session.Session(auth=auth)

# Create the Cinder client
cinder = cinder_client.Client(OS_VOLUME_API_VERSION, session=sess, region_name=OS_REGION_NAME)

# Example: List volumes
try:
    volumes = cinder.volumes.list()
    print(f"Successfully listed volumes: {volumes}")
except Exception as e:
    print(f"Error listing volumes: {e}")

view raw JSON →