Add v3 openstackclient CLI examples

Add some notes about authenticating with v3 keystone and
openstackclient. Also add some examples that don't exist in v2.0,
like domains and groups.

Change-Id: I92f9f9ab3ed4657f0771ad284ee6c4c613eca27c

2 files changed, 202 insertions, 6 deletions

diff --git a/doc/source/cli_examples.rst b/doc/source/cli_examples.rst
index 46f8a97af..25c5c1566 100644
--- a/doc/source/cli_examples.rst
+++ b/doc/source/cli_examples.rst
@@ -31,8 +31,204 @@ packaged in `python-openstackclient`_  supports both v2.0 and v3 APIs.
 .. _`python-openstackclient`: http://docs.openstack.org/developer/python-openstackclient/
 .. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/
 
-Using python-openstackclient
-============================
+Using python-openstackclient (v3)
+=================================
+
+Note that if using ``python-openstackclient`` for v3 commands, the following
+environment variables must be updated:
+
+.. code-block:: bash
+
+    $ export OS_IDENTITY_API_VERSION=3 (Defaults to 2.0)
+    $ export OS_AUTH_URL=http://localhost:5000/v3
+
+Since Identity API v3 authentication is a bit more complex, there are additional
+options that may be set, either as command options or environment variables.
+The most common case will be a user supplying both user name and password, along
+with the project name; previously in v2.0 this would be sufficient, but since
+Identity API v3 has a ``Domain`` component, we need to tell the client in which
+domain the user and project exists.
+
+If using a project name as authorization scope, set either of these:
+
+  * ``--os-project-domain-name OS_PROJECT_DOMAIN_NAME``  Domain name of the project
+    which is the requested project-level authorization scope
+  * ``--os-project-domain-id OS_PROJECT_DOMAIN_ID`` Domain ID of the project which
+    is the requested project-level authorization scope
+
+Note, if using a project ID as authorization scope, then it is not required to
+set ``OS_PROJECT_DOMAIN_NAME`` or ``OS_PROJECT_DOMAIN_ID``, the project ID is
+sufficient.
+
+If using user name and password, set either of these:
+
+  * ``--os-user-domain-name OS_USER_DOMAIN_NAME``  Domain name of the user
+  * ``--os-user-domain-id OS_USER_DOMAIN_ID`` Domain ID of the user
+
+If using a domain as authorization scope, set either of these:
+
+  * ``--os-domain-name OS_DOMAIN_NAME``: Domain name of the requested domain-level
+    authorization scope
+  * ``--os-domain-id OS_DOMAIN_ID``: Domain ID of the requested domain-level
+    authorization scope
+
+In the examples below, the following are set:
+
+.. code-block:: bash
+
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://localhost:5000/v3
+    $ export OS_PROJECT_DOMAIN_ID=default
+    $ export OS_USER_DOMAIN_ID=default
+    $ export OS_USERNAME=admin
+    $ export OS_PASSWORD=openstack
+    $ export OS_PROJECT_NAME=admin
+
+--------
+Projects
+--------
+
+``project create``
+------------------
+
+positional arguments::
+
+  <project-name>                        New project name
+
+optional arguments::
+
+  --description <project-description>   New project description
+  --domain <project-domain>             Domain owning the project (name or ID)
+
+  --enable                              Enable project (default)
+  --disable                             Disable project
+
+example:
+
+.. code-block:: bash
+
+    $ openstack project create heat-project --domain heat
+
+Other commands
+--------------
+
+.. code-block:: bash
+
+  $ openstack project delete
+  $ openstack project list
+  $ openstack project set
+  $ openstack project show
+
+-----
+Users
+-----
+
+``user create``
+---------------
+
+positional arguments::
+
+  <user-name>                  New user name
+
+optional arguments::
+
+  --password <user-password>   New user password
+  --password-prompt            Prompt interactively for password
+  --email <user-email>         New user email address
+  --project <project>          Set default project (name or ID)
+  --domain <domain>            New default domain name or ID
+  --enable                     Enable user (default)
+  --disable                    Disable user
+
+
+example:
+
+.. code-block:: bash
+
+    $ openstack user create heat-user \
+    --password secrete \
+    --domain heat \
+    --project demo \
+    --email admin@example.com
+
+Other commands
+--------------
+
+.. code-block:: bash
+
+  $ openstack user delete
+  $ openstack user list
+  $ openstack user set
+  $ openstack user show
+
+------
+Groups
+------
+
+``group create``
+----------------
+
+positional arguments::
+
+  <group-name>                        New group name
+
+optional arguments::
+
+  --description <group-description>   New group description
+  --domain <group-domain>             References the domain ID or name which owns the group
+
+example:
+
+.. code-block:: bash
+
+    $ openstack group create heat-group --domain heat
+
+Other commands
+--------------
+
+.. code-block:: bash
+
+  $ openstack group delete
+  $ openstack group list
+  $ openstack group set
+  $ openstack group show
+
+-------
+Domains
+-------
+
+``domain create``
+-----------------
+
+positional arguments::
+
+  <domain-name>                        New domain name
+
+optional arguments::
+
+  --description <domain-description>   New domain description
+  --enable                             Enable domain
+  --disable                            Disable domain
+
+
+example:
+
+.. code-block:: bash
+
+  $ openstack domain create heat --description "Heat domain for heat users"
+
+Other commands
+--------------
+
+.. code-block:: bash
+
+  $ openstack domain delete
+  $ openstack domain list
+  $ openstack domain set
+  $ openstack domain show
+
+Using python-openstackclient (v2.0)
+===================================
 
 --------
 Projects
@@ -305,8 +501,8 @@ example:
   $ openstack service delete nova
 
 
-Using python-keystoneclient
-===========================
+Using python-keystoneclient (v2.0)
+==================================
 
 -------
 Tenants
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index ea70ed7df..4254fdc20 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -1239,8 +1239,8 @@ as follows:
 For additional examples using ``python-keystoneclient`` refer to `python-keystoneclient examples`_,
 likewise, for additional examples using ``python-openstackclient``, refer to `python-openstackclient examples`_.
 
-.. _`python-keystoneclient examples`: cli_examples.html#using-python-keystoneclient
-.. _`python-openstackclient examples`: cli_examples.html#using-python-openstackclient
+.. _`python-keystoneclient examples`: cli_examples.html#using-python-keystoneclient-v2-0
+.. _`python-openstackclient examples`: cli_examples.html#using-python-openstackclient-v3
 
 
 Removing Expired Tokens