diff --git a/README.rst b/README.rst index e387b20d3..c1edb054d 100644 --- a/README.rst +++ b/README.rst @@ -78,16 +78,14 @@ params, but it's easier to just set them as environment variables:: export OS_TENANT_NAME=myproject You will also need to define the authentication url with ``--os-auth-url`` -and the version of the API with ``--os-volume-api-version``. Or set them as -environment variables as well:: - - export OS_AUTH_URL=http://example.com:8774/v1.1/ - export OS_VOLUME_API_VERSION=1 - -If you are using Keystone, you need to set the OS_AUTH_URL to the keystone +and the version of the API with ``--os-volume-api-version``. Or set them as +environment variables as well. Since Block Storage API V2 is officially +deprecated, you are encouraged to set ``OS_VOLUME_API_VERSION=3``. If you +are using Keystone, you need to set the ``OS_AUTH_URL`` to the keystone endpoint:: - export OS_AUTH_URL=http://example.com:5000/v2.0/ + export OS_AUTH_URL=http://controller:5000/v3 + export OS_VOLUME_API_VERSION=3 Since Keystone can return multiple regions in the Service Catalog, you can specify the one you want with ``--os-region-name`` (or @@ -96,79 +94,264 @@ can specify the one you want with ``--os-region-name`` (or You'll find complete documentation on the shell by running ``cinder help``:: - usage: cinder [--debug] [--os-username ] - [--os-password ] - [--os-tenant-name ] [--os-auth-url ] - [--os-region-name ] [--service-type ] - [--service-name ] + usage: cinder [--version] [-d] [--os-auth-system ] + [--service-type ] [--service-name ] [--volume-service-name ] + [--os-endpoint-type ] [--endpoint-type ] [--os-volume-api-version ] - [--os-cacert ] [--retries ] + [--bypass-url ] [--retries ] + [--profile HMAC_KEY] [--os-auth-strategy ] + [--os-username ] [--os-password ] + [--os-tenant-name ] + [--os-tenant-id ] [--os-auth-url ] + [--os-user-id ] + [--os-user-domain-id ] + [--os-user-domain-name ] + [--os-project-id ] + [--os-project-name ] + [--os-project-domain-id ] + [--os-project-domain-name ] + [--os-region-name ] [--os-token ] + [--os-url ] [--insecure] [--os-cacert ] + [--os-cert ] [--os-key ] [--timeout ] ... Command-line interface to the OpenStack Cinder API. Positional arguments: - absolute-limits Print a list of absolute limits for a user - create Add a new volume. - credentials Show user credentials returned from auth - delete Remove a volume. - endpoints Discover endpoints that get returned from the - authenticate services - extra-specs-list Print a list of current 'volume types and extra specs' + absolute-limits Lists absolute limits for a user. + api-version Display the server API version information. (Supported + by API versions 3.0 - 3.latest) + availability-zone-list + Lists all availability zones. + backup-create Creates a volume backup. + backup-delete Removes one or more backups. + backup-export Export backup metadata record. + backup-import Import backup metadata record. + backup-list Lists all backups. + backup-reset-state Explicitly updates the backup state. + backup-restore Restores a backup. + backup-show Shows backup details. + cgsnapshot-create Creates a cgsnapshot. + cgsnapshot-delete Removes one or more cgsnapshots. + cgsnapshot-list Lists all cgsnapshots. + cgsnapshot-show Shows cgsnapshot details. + consisgroup-create Creates a consistency group. + consisgroup-create-from-src + Creates a consistency group from a cgsnapshot or a + source CG. + consisgroup-delete Removes one or more consistency groups. + consisgroup-list Lists all consistency groups. + consisgroup-show Shows details of a consistency group. + consisgroup-update Updates a consistency group. + create Creates a volume. + credentials Shows user credentials returned from auth. + delete Removes one or more volumes. + encryption-type-create + Creates encryption type for a volume type. Admin only. + encryption-type-delete + Deletes encryption type for a volume type. Admin only. + encryption-type-list + Shows encryption type details for volume types. Admin + only. + encryption-type-show + Shows encryption type details for a volume type. Admin + only. + encryption-type-update + Update encryption type information for a volume type (Admin Only). - list List all the volumes. - quota-class-show List the quotas for a quota class. - quota-class-update Update the quotas for a quota class. - quota-defaults List the default quotas for a tenant. - quota-show List the quotas for a tenant. - quota-update Update the quotas for a tenant. - rate-limits Print a list of rate limits for a user - rename Rename a volume. - show Show details about a volume. - snapshot-create Add a new snapshot. - snapshot-delete Remove a snapshot. - snapshot-list List all the snapshots. - snapshot-rename Rename a snapshot. - snapshot-show Show details about a snapshot. - type-create Create a new volume type. - type-delete Delete a specific volume type - type-key Set or unset extra_spec for a volume type. - type-list Print a list of available 'volume types'. - bash-completion Prints all of the commands and options to stdout so - that the - help Display help about this program or one of its + endpoints Discovers endpoints registered by authentication + service. + extend Attempts to extend size of an existing volume. + extra-specs-list Lists current volume types and extra specs. + failover-host Failover a replicating cinder-volume host. + force-delete Attempts force-delete of volume, regardless of state. + freeze-host Freeze and disable the specified cinder-volume host. + get-capabilities Show backend volume stats and properties. Admin only. + get-pools Show pool information for backends. Admin only. + image-metadata Sets or deletes volume image metadata. + image-metadata-show + Shows volume image metadata. + list Lists all volumes. + manage Manage an existing volume. + metadata Sets or deletes volume metadata. + metadata-show Shows volume metadata. + metadata-update-all + Updates volume metadata. + migrate Migrates volume to a new host. + qos-associate Associates qos specs with specified volume type. + qos-create Creates a qos specs. + qos-delete Deletes a specified qos specs. + qos-disassociate Disassociates qos specs from specified volume type. + qos-disassociate-all + Disassociates qos specs from all its associations. + qos-get-association + Lists all associations for specified qos specs. + qos-key Sets or unsets specifications for a qos spec. + qos-list Lists qos specs. + qos-show Shows qos specs details. + quota-class-show Lists quotas for a quota class. + quota-class-update Updates quotas for a quota class. + quota-defaults Lists default quotas for a tenant. + quota-delete Delete the quotas for a tenant. + quota-show Lists quotas for a tenant. + quota-update Updates quotas for a tenant. + quota-usage Lists quota usage for a tenant. + rate-limits Lists rate limits for a user. + readonly-mode-update + Updates volume read-only access-mode flag. + rename Renames a volume. + replication-promote + Promote a secondary volume to primary for a + relationship. + replication-reenable + Sync the secondary volume with primary for a + relationship. + reset-state Explicitly updates the volume state in the Cinder + database. + retype Changes the volume type for a volume. + service-disable Disables the service. + service-enable Enables the service. + service-list Lists all services. Filter by host and service binary. + (Supported by API versions 3.0 - 3.latest) + set-bootable Update bootable status of a volume. + show Shows volume details. + snapshot-create Creates a snapshot. + snapshot-delete Removes one or more snapshots. + snapshot-list Lists all snapshots. + snapshot-manage Manage an existing snapshot. + snapshot-metadata Sets or deletes snapshot metadata. + snapshot-metadata-show + Shows snapshot metadata. + snapshot-metadata-update-all + Updates snapshot metadata. + snapshot-rename Renames a snapshot. + snapshot-reset-state + Explicitly updates the snapshot state. + snapshot-show Shows snapshot details. + snapshot-unmanage Stop managing a snapshot. + thaw-host Thaw and enable the specified cinder-volume host. + transfer-accept Accepts a volume transfer. + transfer-create Creates a volume transfer. + transfer-delete Undoes a transfer. + transfer-list Lists all transfers. + transfer-show Shows transfer details. + type-access-add Adds volume type access for the given project. + type-access-list Print access information about the given volume type. + type-access-remove Removes volume type access for the given project. + type-create Creates a volume type. + type-default List the default volume type. + type-delete Deletes volume type or types. + type-key Sets or unsets extra_spec for a volume type. + type-list Lists available 'volume types'. + type-show Show volume type details. + type-update Updates volume type name, description, and/or + is_public. + unmanage Stop managing a volume. + upload-to-image Uploads volume to Image Service as an image. + version-list List all API versions. (Supported by API versions 3.0 + - 3.latest) + bash-completion Prints arguments for bash_completion. + help Shows help about this program or one of its subcommands. - list-extensions List all the os-api extensions that are available. + list-extensions Optional arguments: - -d, --debug Print debugging output - --os-username - Defaults to env[OS_USERNAME]. - --os-password - Defaults to env[OS_PASSWORD]. - --os-tenant-name - Defaults to env[OS_TENANT_NAME]. - --os-auth-url - Defaults to env[OS_AUTH_URL]. - --os-region-name - Defaults to env[OS_REGION_NAME]. + --version show program's version number and exit + -d, --debug Shows debugging output. + --os-auth-system + Defaults to env[OS_AUTH_SYSTEM]. --service-type - Defaults to compute for most actions + Service type. For most actions, default is volume. --service-name - Defaults to env[CINDER_SERVICE_NAME] + Service name. Default=env[CINDER_SERVICE_NAME]. --volume-service-name - Defaults to env[CINDER_VOLUME_SERVICE_NAME] + Volume service name. + Default=env[CINDER_VOLUME_SERVICE_NAME]. + --os-endpoint-type + Endpoint type, which is publicURL or internalURL. + Default=env[OS_ENDPOINT_TYPE] or nova + env[CINDER_ENDPOINT_TYPE] or publicURL. --endpoint-type - Defaults to env[CINDER_ENDPOINT_TYPE] or publicURL. + DEPRECATED! Use --os-endpoint-type. --os-volume-api-version - Defaults to env[OS_VOLUME_API_VERSION]. + Block Storage API version. Accepts X, X.Y (where X is + major and Y is minor + part).Default=env[OS_VOLUME_API_VERSION]. + --bypass-url + Use this API endpoint instead of the Service Catalog. + Defaults to env[CINDERCLIENT_BYPASS_URL]. + --retries Number of retries. + --profile HMAC_KEY HMAC key to use for encrypting context data for + performance profiling of operation. This key needs to + match the one configured on the cinder api server. + Without key the profiling will not be triggered even + if osprofiler is enabled on server side. + --os-auth-strategy + Authentication strategy (Env: OS_AUTH_STRATEGY, + default keystone). For now, any other value will + disable the authentication. + --os-username + OpenStack user name. Default=env[OS_USERNAME]. + --os-password + Password for OpenStack user. Default=env[OS_PASSWORD]. + --os-tenant-name + Tenant name. Default=env[OS_TENANT_NAME]. + --os-tenant-id + ID for the tenant. Default=env[OS_TENANT_ID]. + --os-auth-url + URL for the authentication service. + Default=env[OS_AUTH_URL]. + --os-user-id + Authentication user ID (Env: OS_USER_ID). + --os-user-domain-id + OpenStack user domain ID. Defaults to + env[OS_USER_DOMAIN_ID]. + --os-user-domain-name + OpenStack user domain name. Defaults to + env[OS_USER_DOMAIN_NAME]. + --os-project-id + Another way to specify tenant ID. This option is + mutually exclusive with --os-tenant-id. Defaults to + env[OS_PROJECT_ID]. + --os-project-name + Another way to specify tenant name. This option is + mutually exclusive with --os-tenant-name. Defaults to + env[OS_PROJECT_NAME]. + --os-project-domain-id + Defaults to env[OS_PROJECT_DOMAIN_ID]. + --os-project-domain-name + Defaults to env[OS_PROJECT_DOMAIN_NAME]. + --os-region-name + Region name. Default=env[OS_REGION_NAME]. + --os-token Defaults to env[OS_TOKEN]. + --os-url Defaults to env[OS_URL]. + + API Connection Options: + Options controlling the HTTP API Connections + + --insecure Explicitly allow client to perform "insecure" TLS + (https) requests. The server's certificate will not be + verified against any certificate authorities. This + option should be used with caution. --os-cacert Specify a CA bundle file to use in verifying a TLS - (https) server certificate. Defaults to env[OS_CACERT] - --retries Number of retries. + (https) server certificate. Defaults to + env[OS_CACERT]. + --os-cert + Defaults to env[OS_CERT]. + --os-key Defaults to env[OS_KEY]. + --timeout Set request timeout (in seconds). + + Run "cinder help SUBCOMMAND" for help on a subcommand. + +If you want to get a particular version API help message, you can add +``--os-volume-api-version `` in help command, like +this:: + + cinder --os-volume-api-version 3.28 help Python API ---------- @@ -177,9 +360,9 @@ There's also a complete Python API, but it has not yet been documented. Quick-start using keystone:: - # use v2.0 auth with http://example.com:5000/v2.0/ - >>> from cinderclient.v1 import client - >>> nt = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="volume") + # use v3 auth with http://controller:5000/v3 + >>> from cinderclient.v3 import client + >>> nt = client.Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL) >>> nt.volumes.list() [...]