Update README.rst to remain consistent with python-cinderclient.

The latest python-cinderclient version is 2.0.1, but the content of
project README file is out-of-date. So update README.rst to remain
consistent with python-cinderclient. The changes are as follows:
1. Update OS_AUTH_URL to use Keystone url.
2. Modify OS_VOLUME_API_VERSION to 3(Since API V2 is offical deprecated).
3. Update "cinder help" output.
4. Update python api usage.

Change-Id: Id81eb1c6b0723667bb725b6dabbe7a886a6c7f03

1 files changed, 247 insertions, 64 deletions

diff --git a/README.rst b/README.rst
index e387b20..c1edb05 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 <auth-user-name>]
-                  [--os-password <auth-password>]
-                  [--os-tenant-name <auth-tenant-name>] [--os-auth-url <auth-url>]
-                  [--os-region-name <region-name>] [--service-type <service-type>]
-                  [--service-name <service-name>]
+    usage: cinder [--version] [-d] [--os-auth-system <auth-system>]
+                  [--service-type <service-type>] [--service-name <service-name>]
                   [--volume-service-name <volume-service-name>]
+                  [--os-endpoint-type <os-endpoint-type>]
                   [--endpoint-type <endpoint-type>]
                   [--os-volume-api-version <volume-api-ver>]
-                  [--os-cacert <ca-certificate>] [--retries <retries>]
+                  [--bypass-url <bypass-url>] [--retries <retries>]
+                  [--profile HMAC_KEY] [--os-auth-strategy <auth-strategy>]
+                  [--os-username <auth-user-name>] [--os-password <auth-password>]
+                  [--os-tenant-name <auth-tenant-name>]
+                  [--os-tenant-id <auth-tenant-id>] [--os-auth-url <auth-url>]
+                  [--os-user-id <auth-user-id>]
+                  [--os-user-domain-id <auth-user-domain-id>]
+                  [--os-user-domain-name <auth-user-domain-name>]
+                  [--os-project-id <auth-project-id>]
+                  [--os-project-name <auth-project-name>]
+                  [--os-project-domain-id <auth-project-domain-id>]
+                  [--os-project-domain-name <auth-project-domain-name>]
+                  [--os-region-name <region-name>] [--os-token <token>]
+                  [--os-url <url>] [--insecure] [--os-cacert <ca-certificate>]
+                  [--os-cert <certificate>] [--os-key <key>] [--timeout <seconds>]
                   <subcommand> ...
 
     Command-line interface to the OpenStack Cinder API.
 
     Positional arguments:
       <subcommand>
-        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 <auth-user-name>
-                            Defaults to env[OS_USERNAME].
-      --os-password <auth-password>
-                            Defaults to env[OS_PASSWORD].
-      --os-tenant-name <auth-tenant-name>
-                            Defaults to env[OS_TENANT_NAME].
-      --os-auth-url <auth-url>
-                            Defaults to env[OS_AUTH_URL].
-      --os-region-name <region-name>
-                            Defaults to env[OS_REGION_NAME].
+      --version             show program's version number and exit
+      -d, --debug           Shows debugging output.
+      --os-auth-system <auth-system>
+                            Defaults to env[OS_AUTH_SYSTEM].
       --service-type <service-type>
-                            Defaults to compute for most actions
+                            Service type. For most actions, default is volume.
       --service-name <service-name>
-                            Defaults to env[CINDER_SERVICE_NAME]
+                            Service name. Default=env[CINDER_SERVICE_NAME].
       --volume-service-name <volume-service-name>
-                            Defaults to env[CINDER_VOLUME_SERVICE_NAME]
+                            Volume service name.
+                            Default=env[CINDER_VOLUME_SERVICE_NAME].
+      --os-endpoint-type <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 <endpoint-type>
-                            Defaults to env[CINDER_ENDPOINT_TYPE] or publicURL.
+                            DEPRECATED! Use --os-endpoint-type.
       --os-volume-api-version <volume-api-ver>
-                            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 <bypass-url>
+                            Use this API endpoint instead of the Service Catalog.
+                            Defaults to env[CINDERCLIENT_BYPASS_URL].
+      --retries <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 <auth-strategy>
+                            Authentication strategy (Env: OS_AUTH_STRATEGY,
+                            default keystone). For now, any other value will
+                            disable the authentication.
+      --os-username <auth-user-name>
+                            OpenStack user name. Default=env[OS_USERNAME].
+      --os-password <auth-password>
+                            Password for OpenStack user. Default=env[OS_PASSWORD].
+      --os-tenant-name <auth-tenant-name>
+                            Tenant name. Default=env[OS_TENANT_NAME].
+      --os-tenant-id <auth-tenant-id>
+                            ID for the tenant. Default=env[OS_TENANT_ID].
+      --os-auth-url <auth-url>
+                            URL for the authentication service.
+                            Default=env[OS_AUTH_URL].
+      --os-user-id <auth-user-id>
+                            Authentication user ID (Env: OS_USER_ID).
+      --os-user-domain-id <auth-user-domain-id>
+                            OpenStack user domain ID. Defaults to
+                            env[OS_USER_DOMAIN_ID].
+      --os-user-domain-name <auth-user-domain-name>
+                            OpenStack user domain name. Defaults to
+                            env[OS_USER_DOMAIN_NAME].
+      --os-project-id <auth-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 <auth-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 <auth-project-domain-id>
+                            Defaults to env[OS_PROJECT_DOMAIN_ID].
+      --os-project-domain-name <auth-project-domain-name>
+                            Defaults to env[OS_PROJECT_DOMAIN_NAME].
+      --os-region-name <region-name>
+                            Region name. Default=env[OS_REGION_NAME].
+      --os-token <token>    Defaults to env[OS_TOKEN].
+      --os-url <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 <ca-certificate>
                             Specify a CA bundle file to use in verifying a TLS
-                            (https) server certificate. Defaults to env[OS_CACERT]
-      --retries <retries>   Number of retries.
+                            (https) server certificate. Defaults to
+                            env[OS_CACERT].
+      --os-cert <certificate>
+                            Defaults to env[OS_CERT].
+      --os-key <key>        Defaults to env[OS_KEY].
+      --timeout <seconds>   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 <volume-api-ver>`` 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()
     [...]