{"id":5438,"library":"python-cinderclient","title":"OpenStack Cinder API Client Library","description":"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.","status":"active","version":"9.9.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/python-cinderclient","tags":["openstack","cinder","block storage","cloud","api client"],"install":[{"cmd":"pip install python-cinderclient","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Required for authentication with OpenStack Keystone.","package":"keystoneauth1","optional":false},{"reason":"Common OpenStack utility library.","package":"oslo.utils","optional":false},{"reason":"HTTP library for making API calls.","package":"requests","optional":false}],"imports":[{"note":"Cinder API v3 is the current recommended version. Cinder API v1 and v2 are deprecated.","wrong":"from cinderclient.v1 import client","symbol":"client","correct":"from cinderclient.v3 import client"}],"quickstart":{"code":"import os\nfrom keystoneauth1 import loading\nfrom keystoneauth1 import session\nfrom cinderclient.v3 import client as cinder_client\n\n# Set environment variables or replace with actual values\nOS_AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')\nOS_USERNAME = os.environ.get('OS_USERNAME', 'admin')\nOS_PASSWORD = os.environ.get('OS_PASSWORD', 'password')\nOS_PROJECT_ID = os.environ.get('OS_PROJECT_ID', 'project_id') # Or OS_PROJECT_NAME\nOS_REGION_NAME = os.environ.get('OS_REGION_NAME', 'RegionOne')\nOS_VOLUME_API_VERSION = os.environ.get('OS_VOLUME_API_VERSION', '3')\n\n# Load the authentication plugin\nloader = loading.get_plugin_loader('password')\nauth = loader.load_from_options(\n    auth_url=OS_AUTH_URL,\n    username=OS_USERNAME,\n    password=OS_PASSWORD,\n    project_id=OS_PROJECT_ID, # Use project_id or project_name\n    user_domain_name='Default', # Often 'Default' for typical OpenStack setups\n    project_domain_name='Default'\n)\n\n# Create a session\nsess = session.Session(auth=auth)\n\n# Create the Cinder client\ncinder = cinder_client.Client(OS_VOLUME_API_VERSION, session=sess, region_name=OS_REGION_NAME)\n\n# Example: List volumes\ntry:\n    volumes = cinder.volumes.list()\n    print(f\"Successfully listed volumes: {volumes}\")\nexcept Exception as e:\n    print(f\"Error listing volumes: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"< 9.x (specifically older API versions accessed through the client)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using the `cinder` CLI, replace `--endpoint-type` with `--os-endpoint-type`.","message":"The `--endpoint-type` CLI option has been deprecated. Users should utilize `--os-endpoint-type` instead when interacting via the command line.","severity":"deprecated","affected_versions":"All 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.","message":"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.","severity":"breaking","affected_versions":"1.2.0, 1.2.2"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}