README.rst
1========================
2Team and repository tags
3========================
4
5.. image:: https://governance.openstack.org/tc/badges/python-cinderclient.svg
6 :target: https://governance.openstack.org/tc/reference/tags/index.html
7
8.. Change things from this point on
9
10Python bindings to the OpenStack Cinder API
11===========================================
12
13.. image:: https://img.shields.io/pypi/v/python-cinderclient.svg
14 :target: https://pypi.org/project/python-cinderclient/
15 :alt: Latest Version
16
17This is a client for the OpenStack Cinder API. There's a Python API (the
18``cinderclient`` module), and a command-line script (``cinder``). Each
19implements 100% of the OpenStack Cinder API.
20
21See the `OpenStack CLI Reference`_ for information on how to use the ``cinder``
22command-line tool. You may also want to look at the
23`OpenStack API documentation`_.
24
25.. _OpenStack CLI Reference: https://docs.openstack.org/python-openstackclient/latest/cli/
26.. _OpenStack API documentation: https://docs.openstack.org/api-quick-start/
27
28The project is hosted on `Launchpad`_, where bugs can be filed. The code is
29hosted on `OpenStack`_. Patches must be submitted using `Gerrit`_.
30
31.. _OpenStack: https://opendev.org/openstack/python-cinderclient
32.. _Launchpad: https://launchpad.net/python-cinderclient
33.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
34
35* License: Apache License, Version 2.0
36* `PyPi`_ - package installation
37* `Online Documentation`_
38* `Blueprints`_ - feature specifications
39* `Bugs`_ - issue tracking
40* `Source`_
41* `Specs`_
42* `How to Contribute`_
43
44.. _PyPi: https://pypi.org/project/python-cinderclient
45.. _Online Documentation: https://docs.openstack.org/python-cinderclient/latest/
46.. _Blueprints: https://blueprints.launchpad.net/python-cinderclient
47.. _Bugs: https://bugs.launchpad.net/python-cinderclient
48.. _Source: https://opendev.org/openstack/python-cinderclient
49.. _How to Contribute: https://docs.openstack.org/infra/manual/developers.html
50.. _Specs: https://specs.openstack.org/openstack/cinder-specs/
51
52
53.. contents:: Contents:
54 :local:
55
56Command-line API
57----------------
58
59Installing this package gets you a shell command, ``cinder``, that you
60can use to interact with any Rackspace compatible API (including OpenStack).
61
62You'll need to provide your OpenStack username and password. You can do this
63with the ``--os-username``, ``--os-password`` and ``--os-tenant-name``
64params, but it's easier to just set them as environment variables::
65
66 export OS_USERNAME=openstack
67 export OS_PASSWORD=yadayada
68 export OS_TENANT_NAME=myproject
69
70You will also need to define the authentication url with ``--os-auth-url``
71and the version of the API with ``--os-volume-api-version``. Or set them as
72environment variables as well. Since Block Storage API V2 is officially
73deprecated, you are encouraged to set ``OS_VOLUME_API_VERSION=3``. If you
74are using Keystone, you need to set the ``OS_AUTH_URL`` to the keystone
75endpoint::
76
77 export OS_AUTH_URL=http://controller:5000/v3
78 export OS_VOLUME_API_VERSION=3
79
80Since Keystone can return multiple regions in the Service Catalog, you
81can specify the one you want with ``--os-region-name`` (or
82``export OS_REGION_NAME``). It defaults to the first in the list returned.
83
84You'll find complete documentation on the shell by running
85``cinder help``::
86
87 usage: cinder [--version] [-d] [--os-auth-system <auth-system>]
88 [--service-type <service-type>] [--service-name <service-name>]
89 [--volume-service-name <volume-service-name>]
90 [--os-endpoint-type <os-endpoint-type>]
91 [--endpoint-type <endpoint-type>]
92 [--os-volume-api-version <volume-api-ver>]
93 [--retries <retries>]
94 [--profile HMAC_KEY] [--os-auth-strategy <auth-strategy>]
95 [--os-username <auth-user-name>] [--os-password <auth-password>]
96 [--os-tenant-name <auth-tenant-name>]
97 [--os-tenant-id <auth-tenant-id>] [--os-auth-url <auth-url>]
98 [--os-user-id <auth-user-id>]
99 [--os-user-domain-id <auth-user-domain-id>]
100 [--os-user-domain-name <auth-user-domain-name>]
101 [--os-project-id <auth-project-id>]
102 [--os-project-name <auth-project-name>]
103 [--os-project-domain-id <auth-project-domain-id>]
104 [--os-project-domain-name <auth-project-domain-name>]
105 [--os-region-name <region-name>] [--os-token <token>]
106 [--os-url <url>] [--insecure] [--os-cacert <ca-certificate>]
107 [--os-cert <certificate>] [--os-key <key>] [--timeout <seconds>]
108 <subcommand> ...
109
110 Command-line interface to the OpenStack Cinder API.
111
112 Positional arguments:
113 <subcommand>
114 absolute-limits Lists absolute limits for a user.
115 api-version Display the server API version information. (Supported
116 by API versions 3.0 - 3.latest)
117 availability-zone-list
118 Lists all availability zones.
119 backup-create Creates a volume backup.
120 backup-delete Removes one or more backups.
121 backup-export Export backup metadata record.
122 backup-import Import backup metadata record.
123 backup-list Lists all backups.
124 backup-reset-state Explicitly updates the backup state.
125 backup-restore Restores a backup.
126 backup-show Shows backup details.
127 cgsnapshot-create Creates a cgsnapshot.
128 cgsnapshot-delete Removes one or more cgsnapshots.
129 cgsnapshot-list Lists all cgsnapshots.
130 cgsnapshot-show Shows cgsnapshot details.
131 consisgroup-create Creates a consistency group.
132 consisgroup-create-from-src
133 Creates a consistency group from a cgsnapshot or a
134 source CG.
135 consisgroup-delete Removes one or more consistency groups.
136 consisgroup-list Lists all consistency groups.
137 consisgroup-show Shows details of a consistency group.
138 consisgroup-update Updates a consistency group.
139 create Creates a volume.
140 credentials Shows user credentials returned from auth.
141 delete Removes one or more volumes.
142 encryption-type-create
143 Creates encryption type for a volume type. Admin only.
144 encryption-type-delete
145 Deletes encryption type for a volume type. Admin only.
146 encryption-type-list
147 Shows encryption type details for volume types. Admin
148 only.
149 encryption-type-show
150 Shows encryption type details for a volume type. Admin
151 only.
152 encryption-type-update
153 Update encryption type information for a volume type
154 (Admin Only).
155 endpoints Discovers endpoints registered by authentication
156 service.
157 extend Attempts to extend size of an existing volume.
158 extra-specs-list Lists current volume types and extra specs.
159 failover-host Failover a replicating cinder-volume host.
160 force-delete Attempts force-delete of volume, regardless of state.
161 freeze-host Freeze and disable the specified cinder-volume host.
162 get-capabilities Show backend volume stats and properties. Admin only.
163 get-pools Show pool information for backends. Admin only.
164 image-metadata Sets or deletes volume image metadata.
165 image-metadata-show
166 Shows volume image metadata.
167 list Lists all volumes.
168 manage Manage an existing volume.
169 metadata Sets or deletes volume metadata.
170 metadata-show Shows volume metadata.
171 metadata-update-all
172 Updates volume metadata.
173 migrate Migrates volume to a new host.
174 qos-associate Associates qos specs with specified volume type.
175 qos-create Creates a qos specs.
176 qos-delete Deletes a specified qos specs.
177 qos-disassociate Disassociates qos specs from specified volume type.
178 qos-disassociate-all
179 Disassociates qos specs from all its associations.
180 qos-get-association
181 Lists all associations for specified qos specs.
182 qos-key Sets or unsets specifications for a qos spec.
183 qos-list Lists qos specs.
184 qos-show Shows qos specs details.
185 quota-class-show Lists quotas for a quota class.
186 quota-class-update Updates quotas for a quota class.
187 quota-defaults Lists default quotas for a tenant.
188 quota-delete Delete the quotas for a tenant.
189 quota-show Lists quotas for a tenant.
190 quota-update Updates quotas for a tenant.
191 quota-usage Lists quota usage for a tenant.
192 rate-limits Lists rate limits for a user.
193 readonly-mode-update
194 Updates volume read-only access-mode flag.
195 rename Renames a volume.
196 reset-state Explicitly updates the volume state in the Cinder
197 database.
198 retype Changes the volume type for a volume.
199 service-disable Disables the service.
200 service-enable Enables the service.
201 service-list Lists all services. Filter by host and service binary.
202 (Supported by API versions 3.0 - 3.latest)
203 set-bootable Update bootable status of a volume.
204 show Shows volume details.
205 snapshot-create Creates a snapshot.
206 snapshot-delete Removes one or more snapshots.
207 snapshot-list Lists all snapshots.
208 snapshot-manage Manage an existing snapshot.
209 snapshot-metadata Sets or deletes snapshot metadata.
210 snapshot-metadata-show
211 Shows snapshot metadata.
212 snapshot-metadata-update-all
213 Updates snapshot metadata.
214 snapshot-rename Renames a snapshot.
215 snapshot-reset-state
216 Explicitly updates the snapshot state.
217 snapshot-show Shows snapshot details.
218 snapshot-unmanage Stop managing a snapshot.
219 thaw-host Thaw and enable the specified cinder-volume host.
220 transfer-accept Accepts a volume transfer.
221 transfer-create Creates a volume transfer.
222 transfer-delete Undoes a transfer.
223 transfer-list Lists all transfers.
224 transfer-show Shows transfer details.
225 type-access-add Adds volume type access for the given project.
226 type-access-list Print access information about the given volume type.
227 type-access-remove Removes volume type access for the given project.
228 type-create Creates a volume type.
229 type-default List the default volume type.
230 type-delete Deletes volume type or types.
231 type-key Sets or unsets extra_spec for a volume type.
232 type-list Lists available 'volume types'.
233 type-show Show volume type details.
234 type-update Updates volume type name, description, and/or
235 is_public.
236 unmanage Stop managing a volume.
237 upload-to-image Uploads volume to Image Service as an image.
238 version-list List all API versions. (Supported by API versions 3.0
239 - 3.latest)
240 bash-completion Prints arguments for bash_completion.
241 help Shows help about this program or one of its
242 subcommands.
243 list-extensions
244
245 Optional arguments:
246 --version show program's version number and exit
247 -d, --debug Shows debugging output.
248 --os-auth-system <auth-system>
249 Defaults to env[OS_AUTH_SYSTEM].
250 --service-type <service-type>
251 Service type. For most actions, default is volume.
252 --service-name <service-name>
253 Service name. Default=env[CINDER_SERVICE_NAME].
254 --volume-service-name <volume-service-name>
255 Volume service name.
256 Default=env[CINDER_VOLUME_SERVICE_NAME].
257 --os-endpoint
258 Use this API endpoint instead of the Service Catalog.
259 Default=env[CINDER_ENDPOINT]
260 --os-endpoint-type <os-endpoint-type>
261 Endpoint type, which is publicURL or internalURL.
262 Default=env[OS_ENDPOINT_TYPE] or nova
263 env[CINDER_ENDPOINT_TYPE] or publicURL.
264 --endpoint-type <endpoint-type>
265 DEPRECATED! Use --os-endpoint-type.
266 --os-volume-api-version <volume-api-ver>
267 Block Storage API version. Accepts X, X.Y (where X is
268 major and Y is minor
269 part).Default=env[OS_VOLUME_API_VERSION].
270 --retries <retries> Number of retries.
271 --profile HMAC_KEY HMAC key to use for encrypting context data for
272 performance profiling of operation. This key needs to
273 match the one configured on the cinder api server.
274 Without key the profiling will not be triggered even
275 if osprofiler is enabled on server side.
276 Defaults to env[OS_PROFILE].
277 --os-auth-strategy <auth-strategy>
278 Authentication strategy (Env: OS_AUTH_STRATEGY,
279 default keystone). For now, any other value will
280 disable the authentication.
281 --os-username <auth-user-name>
282 OpenStack user name. Default=env[OS_USERNAME].
283 --os-password <auth-password>
284 Password for OpenStack user. Default=env[OS_PASSWORD].
285 --os-tenant-name <auth-tenant-name>
286 Tenant name. Default=env[OS_TENANT_NAME].
287 --os-tenant-id <auth-tenant-id>
288 ID for the tenant. Default=env[OS_TENANT_ID].
289 --os-auth-url <auth-url>
290 URL for the authentication service.
291 Default=env[OS_AUTH_URL].
292 --os-user-id <auth-user-id>
293 Authentication user ID (Env: OS_USER_ID).
294 --os-user-domain-id <auth-user-domain-id>
295 OpenStack user domain ID. Defaults to
296 env[OS_USER_DOMAIN_ID].
297 --os-user-domain-name <auth-user-domain-name>
298 OpenStack user domain name. Defaults to
299 env[OS_USER_DOMAIN_NAME].
300 --os-project-id <auth-project-id>
301 Another way to specify tenant ID. This option is
302 mutually exclusive with --os-tenant-id. Defaults to
303 env[OS_PROJECT_ID].
304 --os-project-name <auth-project-name>
305 Another way to specify tenant name. This option is
306 mutually exclusive with --os-tenant-name. Defaults to
307 env[OS_PROJECT_NAME].
308 --os-project-domain-id <auth-project-domain-id>
309 Defaults to env[OS_PROJECT_DOMAIN_ID].
310 --os-project-domain-name <auth-project-domain-name>
311 Defaults to env[OS_PROJECT_DOMAIN_NAME].
312 --os-region-name <region-name>
313 Region name. Default=env[OS_REGION_NAME].
314 --os-token <token> Defaults to env[OS_TOKEN].
315 --os-url <url> Defaults to env[OS_URL].
316
317 API Connection Options:
318 Options controlling the HTTP API Connections
319
320 --insecure Explicitly allow client to perform "insecure" TLS
321 (https) requests. The server's certificate will not be
322 verified against any certificate authorities. This
323 option should be used with caution.
324 --os-cacert <ca-certificate>
325 Specify a CA bundle file to use in verifying a TLS
326 (https) server certificate. Defaults to
327 env[OS_CACERT].
328 --os-cert <certificate>
329 Defaults to env[OS_CERT].
330 --os-key <key> Defaults to env[OS_KEY].
331 --timeout <seconds> Set request timeout (in seconds).
332
333 Run "cinder help SUBCOMMAND" for help on a subcommand.
334
335If you want to get a particular version API help message, you can add
336``--os-volume-api-version <volume-api-ver>`` in help command, like
337this::
338
339 cinder --os-volume-api-version 3.28 help
340
341Python API
342----------
343
344There's also a complete Python API, but it has not yet been documented.
345
346Quick-start using keystone::
347
348 # use v3 auth with http://controller:5000/v3
349 >>> from cinderclient.v3 import client
350 >>> nt = client.Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL)
351 >>> nt.volumes.list()
352 [...]
353
354See release notes and more at `<https://docs.openstack.org/python-cinderclient/latest/>`_.
355
