1.5.0-1 (patches unapplied)import/1.5.0-1

Imported using git-ubuntu import.
author: Corey Bryant <corey.bryant@canonical.com> 2015-06-22 16:07:31 +0100
committer: git-ubuntu importer <ubuntu-devel-discuss@lists.ubuntu.com> 2015-06-22 22:10:41 +0000
commit: f3e023ac0edd14f64b870dd0c81152248d26870e (patch)
tree: 05d8a27edc3836757a1c8edddc5e7568e64ed0a9 /doc
parent: ae5b9e8ef6e165eb7cfa9b6e447a62f226a3bee9 (diff)
20 files changed, 946 insertions, 21 deletions
diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst
index 5acfe33..bf23b66 100644
--- a/doc/source/authentication.rst
+++ b/doc/source/authentication.rst
@@ -62,8 +62,11 @@ by the ``ClientManager`` object.
     plugins from the ``keystoneclient.auth.plugin`` entry point.
   * builds a list of authentication options from the plugins.
 
+* The command line arguments are processed and a configuration is loaded from
+  :file:`clouds.yaml` if ``--os-cloud`` is provided.
+
 * A new ``ClientManager`` is created and supplied with the set of options from the
-  command line and/or environment:
+  command line, environment and/or :file:`clouds.yaml`:
 
   * If ``--os-auth-type`` is provided and is a valid and available plugin
       it is used.
@@ -71,7 +74,7 @@ by the ``ClientManager`` object.
     is selected based on the existing options.  This is a short-circuit
     evaluation, the first match wins.
 
-    * If ``--os-endpoint`` and ``--os-token`` are both present ``token_endpoint``
+    * If ``--os-url`` and ``--os-token`` are both present ``token_endpoint``
       is selected
     * If ``--os-username`` is supplied ``password`` is selected
     * If ``--os-token`` is supplied ``token`` is selected
@@ -84,3 +87,58 @@ by the ``ClientManager`` object.
 
   * if ``--os-auth-url`` is not supplied for any of the types except
     Token/Endpoint, exit with an error.
+
+Authenticating using Identity Server API v3
+-------------------------------------------
+
+To authenticate against an Identity Server API v3, the
+``OS_IDENTITY_API_VERSION`` environment variable or
+``--os-identity-api-version`` option must be changed to ``3``, instead of the
+default ``2.0``. Similarly ``OS_AUTH_URL`` or ``os-auth-url`` should also 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 line 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 the Identity API v3 has a ``Domain`` component, we need
+to tell the client in which domain the user and project exists.
+
+If using a user name and password to authenticate, specify either it's owning
+domain name or ID.
+
+  * ``--os-user-domain-name`` or ``OS_USER_DOMAIN_NAME``
+
+  * ``--os-user-domain-id`` or ``OS_USER_DOMAIN_ID``
+
+If using a project name as authorization scope, specify either it's owning
+domain name or ID.
+
+  * ``--os-project-domain-name`` or ``OS_PROJECT_DOMAIN_NAME``
+
+  * ``--os-project-domain-id`` or ``OS_PROJECT_DOMAIN_ID``
+
+If using a domain as authorization scope, set either it's name or ID.
+
+  * ``--os-domain-name`` or ``OS_DOMAIN_NAME``
+
+  * ``--os-domain-id`` or ``OS_DOMAIN_ID``
+
+Note that if the user and project share the same domain, then simply setting
+``os-default-domain`` or ``OS_DEFAULT_DOMAIN`` is sufficient.
+
+Thus, a minimal set of of environment variables would be:
+
+.. code-block:: bash
+
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://localhost:5000/v3
+    $ export OS_DEFAULT_DOMAIN=default
+    $ export OS_USERNAME=admin
+    $ export OS_PASSWORD=secret
+    $ export OS_PROJECT_NAME=admin
diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst
new file mode 100644
index 0000000..437f932
--- /dev/null
+++ b/doc/source/backwards-incompatible.rst
@@ -0,0 +1,59 @@
+==============================
+Backwards Incompatible Changes
+==============================
+
+Despite our best efforts, sometimes the OpenStackClient team may introduce a
+backwards incompatible change. For user convenience we are tracking any such
+changes here (as of the 1.0.0 release).
+
+Should positional arguments for a command need to change, the OpenStackClient
+team attempts to make the transition as painless as possible. Look for
+deprecation warnings that indicate the new commands (or options) to use.
+
+List of Backwards Incompatible Changes
+======================================
+
+1. Rename command `openstack project usage list`
+
+  The `project` part of the command was pointless.
+
+  * In favor of: `openstack usage list` instead.
+  * As of: 1.0.2
+  * Removed in: TBD
+  * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1406654
+  * Commit: https://review.openstack.org/#/c/147379/
+
+2. <type> should not be optional for command `openstack service create`
+
+  Previously, the command was `openstack service create <name> --type <type>`,
+  whereas now it is: `openstack service create <type> --name <name>`
+  This bug also affected python-keystoneclient, and keystone.
+
+  * In favor of: making <type> a positional argument.
+  * As of: 1.0.2
+  * Removed in: TBD
+  * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1404073
+  * Commit: https://review.openstack.org/#/c/143242/
+
+3. Command `openstack security group rule delete` now requires rule id
+
+  Previously, the command was `openstack security group rule delete --proto
+  <proto> [--src-ip <ip-address> --dst-port <port-range>] <group>`,
+  whereas now it is: `openstack security group rule delete <rule>`.
+
+  * In favor of: Using `openstack security group rule delete <rule>`.
+  * As of: 1.2.1
+  * Removed in: NA
+  * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1450872
+  * Commit: https://review.openstack.org/#/c/179446/
+
+For Developers
+==============
+
+If introducing a backwards incompatible change, then add the tag:
+``BackwardsIncompatibleImpact`` to your git commit message, and if possible,
+update this file.
+
+To review all changes that are affected, use the following query:
+
+https://review.openstack.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z
diff --git a/doc/source/command-objects/ec2-credentials.rst b/doc/source/command-objects/ec2-credentials.rst
index a5b6754..f8e3856 100644
--- a/doc/source/command-objects/ec2-credentials.rst
+++ b/doc/source/command-objects/ec2-credentials.rst
@@ -15,14 +15,31 @@ Create EC2 credentials
     os ec2 credentials create
         [--project <project>]
         [--user <user>]
+        [--user-domain <user-domain>]
+        [--project-domain <project-domain>]
 
 .. option:: --project <project>
 
-    Specify an alternate project (default: current authenticated project)
+    Create credentials in project (name or ID; default: current authenticated project)
 
 .. option:: --user <user>
 
-    Specify an alternate user (default: current authenticated user)
+    Create credentials for user (name or ID; default: current authenticated user)
+
+.. option:: --user-domain <user-domain>
+
+    Select user from a specific domain (name or ID)
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
+.. option:: --project-domain <project-domain>
+
+    Select project from a specific domain (name or ID)
+    This can be used in case collisions between project names exist.
+
+    .. versionadded:: 3
+
 
 The :option:`--project` and :option:`--user`  options are typically only
 useful for admin users, but may be allowed for other users depending on
@@ -38,11 +55,19 @@ Delete EC2 credentials
 
     os ec2 credentials delete
         [--user <user>]
+        [--user-domain <user-domain>]
         <access-key>
 
 .. option:: --user <user>
 
-    Specify a user
+    Delete credentials for user (name or ID)
+
+.. option:: --user-domain <user-domain>
+
+    Select user from a specific domain (name or ID)
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
 
 .. _ec2_credentials_delete-access-key:
 .. describe:: access-key
@@ -63,10 +88,18 @@ List EC2 credentials
 
     os ec2 credentials list
         [--user <user>]
+        [--user-domain <user-domain>]
 
 .. option:: --user <user>
 
-    Filter list by <user>
+    Filter list by <user> (name or ID)
+
+.. option:: --user-domain <user-domain>
+
+    Select user from a specific domain (name or ID)
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
 
 The :option:`--user` option is typically only useful for admin users, but
 may be allowed for other users depending on the policy of the cloud and
@@ -82,11 +115,19 @@ Display EC2 credentials details
 
     os ec2 credentials show
         [--user <user>]
+        [--user-domain <user-domain>]
         <access-key>
 
 .. option:: --user <user>
 
-    Specify a user
+    Show credentials for user (name or ID)
+
+.. option:: --user-domain <user-domain>
+
+    Select user from a specific domain (name or ID)
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
 
 .. _ec2_credentials_show-access-key:
 .. describe:: access-key
diff --git a/doc/source/command-objects/flavor.rst b/doc/source/command-objects/flavor.rst
index fa9fd80..5254b12 100644
--- a/doc/source/command-objects/flavor.rst
+++ b/doc/source/command-objects/flavor.rst
@@ -123,3 +123,43 @@ Display flavor details
 .. describe:: <flavor>
 
     Flavor to display (name or ID)
+
+flavor set
+----------
+
+Set flavor properties
+
+.. program:: flavor set
+.. code:: bash
+
+    os flavor set
+        [--property <key=value> [...] ]
+        <flavor>
+
+.. option:: --property <key=value>
+
+    Property to add or modify for this flavor (repeat option to set multiple properties)
+
+.. describe:: <flavor>
+
+    Flavor to modify (name or ID)
+
+flavor unset
+------------
+
+Unset flavor properties
+
+.. program:: flavor unset
+.. code:: bash
+
+    os flavor unset
+        [--property <key> [...] ]
+        <flavor>
+
+.. option:: --property <key>
+
+    Property to remove from flavor (repeat option to remove multiple properties)
+
+.. describe:: <flavor>
+
+    Flavor to modify (name or ID)
diff --git a/doc/source/command-objects/group.rst b/doc/source/command-objects/group.rst
index 6c38505..0f2c5cd 100644
--- a/doc/source/command-objects/group.rst
+++ b/doc/source/command-objects/group.rst
@@ -13,9 +13,25 @@ Add user to group
 .. code:: bash
 
     os group add user
+        [--group-domain <group-domain>]
+        [--user-domain <user-domain>]
         <group>
         <user>
 
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID). This can be
+    used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID). This can be
+    used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
 .. describe:: <group>
 
     Group to contain <user> (name or ID)
@@ -33,9 +49,25 @@ Check user membership in group
 .. code:: bash
 
     os group contains user
+        [--group-domain <group-domain>]
+        [--user-domain <user-domain>]
         <group>
         <user>
 
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID). This can be
+    used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID). This can be
+    used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
 .. describe:: <group>
 
     Group to check (name or ID)
@@ -106,7 +138,7 @@ List groups
 
     os group list
         [--domain <domain>]
-        [--user <user>]
+        [--user <user> [--user-domain <user-domain>]]
         [--long]
 
 .. option:: --domain <domain>
@@ -117,6 +149,13 @@ List groups
 
     Filter group list by <user> (name or ID)
 
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID). This can be
+    used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
 .. option:: --long
 
     List additional fields in output
@@ -130,9 +169,25 @@ Remove user from group
 .. code:: bash
 
     os group remove user
+        [--group-domain <group-domain>]
+        [--user-domain <user-domain>]
         <group>
         <user>
 
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID). This can be
+    used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID). This can be
+    used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
 .. describe:: <group>
 
     Group containing <user> (name or ID)
@@ -150,10 +205,15 @@ Set group properties
 .. code:: bash
 
     os group set
+        [--domain <domain>]
         [--name <name>]
         [--description <description>]
         <group>
 
+.. option:: --domain <domain>
+
+    Domain containing <group> (name or ID)
+
 .. option:: --name <name>
 
     New group name
diff --git a/doc/source/command-objects/identity-provider.rst b/doc/source/command-objects/identity-provider.rst
index 47e274d..90f0b49 100644
--- a/doc/source/command-objects/identity-provider.rst
+++ b/doc/source/command-objects/identity-provider.rst
@@ -15,10 +15,21 @@ Create new identity provider
 .. code:: bash
 
     os identity provider create
+        [--remote-id <remote-id> [...] | --remote-id-file <file-name>]
         [--description <description>]
         [--enable | --disable]
         <name>
 
+.. option:: --remote-id <remote-id>
+
+    Remote IDs to associate with the Identity Provider (repeat to provide
+    multiple values)
+
+.. option:: --remote-id-file <file-name>
+
+    Name of a file that contains many remote IDs to associate with the identity
+    provider, one per line
+
 .. option:: --description
 
     New identity provider description
@@ -69,9 +80,20 @@ Set identity provider properties
 .. code:: bash
 
     os identity provider set
+        [--remote-id <remote-id> [...] | --remote-id-file <file-name>]
         [--enable | --disable]
         <identity-provider>
 
+.. option:: --remote-id <remote-id>
+
+    Remote IDs to associate with the Identity Provider (repeat to provide
+    multiple values)
+
+.. option:: --remote-id-file <file-name>
+
+    Name of a file that contains many remote IDs to associate with the identity
+    provider, one per line
+
 .. option:: --enable
 
     Enable the identity provider
diff --git a/doc/source/command-objects/image.rst b/doc/source/command-objects/image.rst
index 83036a6..1865865 100644
--- a/doc/source/command-objects/image.rst
+++ b/doc/source/command-objects/image.rst
@@ -205,6 +205,9 @@ Set image properties
         [--owner <project>]
         [--min-disk <disk-gb>]
         [--min-ram <disk-ram>]
+        [--container-format <container-format>]
+        [--disk-format <disk-format>]
+        [--size <size>]
         [--protected | --unprotected]
         [--public | --private]
         [--property <key=value> [...] ]
@@ -226,6 +229,21 @@ Set image properties
 
     Minimum RAM size needed to boot image, in megabytes
 
+.. option:: --container-format <container-format>
+
+    Container format of image.
+    Acceptable formats: ['ami', 'ari', 'aki', 'bare', 'ovf']
+
+.. option:: --disk-format <disk-format>
+
+    Disk format of image.
+    Acceptable formats: ['ami', 'ari', 'aki', 'vhd', 'vmdk', 'raw', 'qcow2',
+                         'vdi', 'iso']
+
+.. option:: --size <size>
+
+    Size of image data (in bytes)
+
 .. option:: --protected
 
     Prevent image from being deleted
diff --git a/doc/source/command-objects/limits.rst b/doc/source/command-objects/limits.rst
index 1eae488..0d466af 100644
--- a/doc/source/command-objects/limits.rst
+++ b/doc/source/command-objects/limits.rst
@@ -16,6 +16,8 @@ Show compute and volume limits
 
     os limits show
         --absolute [--reserved] | --rate
+        [--project <project>]
+        [--domain <domain>]
 
 .. option:: --absolute
 
@@ -28,3 +30,11 @@ Show compute and volume limits
 .. option:: --reserved
 
     Include reservations count [only valid with :option:`--absolute`]
+
+.. option:: --project <project>
+
+    Show limits for a specific project (name or ID) [only valid with --absolute]
+
+.. option:: --domain <domain>
+
+    Domain that owns --project (name or ID) [only valid with --absolute]
diff --git a/doc/source/command-objects/network.rst b/doc/source/command-objects/network.rst
index 0edd298..dcba9f8 100644
--- a/doc/source/command-objects/network.rst
+++ b/doc/source/command-objects/network.rst
@@ -13,10 +13,20 @@ Create new network
 .. code:: bash
 
     os network create
+        [--domain <domain>]
         [--enable | --disable]
+        [--project <project>]
         [--share | --no-share]
         <name>
 
+.. option:: --domain <domain>
+
+    Owner's domain (name or ID)"
+
+.. option:: --project <project>
+
+    Owner's project (name or ID)
+
 .. option:: --enable
 
     Enable network (default)
diff --git a/doc/source/command-objects/project.rst b/doc/source/command-objects/project.rst
index 422e239..63796da 100644
--- a/doc/source/command-objects/project.rst
+++ b/doc/source/command-objects/project.rst
@@ -14,6 +14,7 @@ Create new project
 
     os project create
         [--domain <domain>]
+        [--parent <project>]
         [--description <description>]
         [--enable | --disable]
         [--property <key=value>]
@@ -25,6 +26,12 @@ Create new project
 
     .. versionadded:: 3
 
+.. option:: --parent <project>
+
+    Parent of the project (name or ID)
+
+    .. versionadded:: 3
+
 .. option:: --description <description>
 
     Project description
@@ -118,6 +125,12 @@ Set project properties
 
     Set project name
 
+.. option:: --domain <domain>
+
+    Domain owning :ref:`\<project\> <project_set-project>` (name or ID)
+
+    .. versionadded:: 3
+
 .. option:: --description <description>
 
     Set project description
diff --git a/doc/source/command-objects/quota.rst b/doc/source/command-objects/quota.rst
index 053fb47..5ea49f8 100644
--- a/doc/source/command-objects/quota.rst
+++ b/doc/source/command-objects/quota.rst
@@ -30,6 +30,7 @@ Set quotas for project
         [--gigabytes <new-gigabytes>]
         [--snapshots <new-snapshots>]
         [--volumes <new-volumes>]
+        [--volume-type <volume-type>]
 
         <project>
 
@@ -121,6 +122,10 @@ Set quotas for class
 
     New value for the snapshots quota
 
+.. option:: --volume-type <volume-type>
+
+    Set quotas for a specific <volume-type>
+
 quota show
 ----------
 
diff --git a/doc/source/command-objects/role.rst b/doc/source/command-objects/role.rst
index 02766b0..dad5642 100644
--- a/doc/source/command-objects/role.rst
+++ b/doc/source/command-objects/role.rst
@@ -13,8 +13,8 @@ Add role to a user or group in a project or domain
 .. code:: bash
 
     os role add
-        --domain <domain> | --project <project>
-        --user <user> | --group <group>
+        --domain <domain> | --project <project> [--project-domain <project-domain>]
+        --user <user> [--user-domain <user-domain>] | --group <group> [--group-domain <group-domain>]
         <role>
 
 .. option:: --domain <domain>
@@ -37,6 +37,27 @@ Add role to a user or group in a project or domain
 
     .. versionadded:: 3
 
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID).
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID).
+    This can be used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --project-domain <project-domain>
+
+    Domain the project belongs to (name or ID).
+    This can be used in case collisions between project names exist.
+
+    .. versionadded:: 3
+
 .. describe:: <role>
 
     Role to add to `<project>`:`<user>` (name or ID)
@@ -80,8 +101,8 @@ List roles
 .. code:: bash
 
     os role list
-        [--domain <domain> | --project <project]
-        [--user <user> | --group <group>]
+        --domain <domain> | --project <project> [--project-domain <project-domain>]
+        --user <user> [--user-domain <user-domain>] | --group <group> [--group-domain <group-domain>]
 
 .. option:: --domain <domain>
 
@@ -107,6 +128,27 @@ List roles
 
     .. versionadded:: 3
 
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID).
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID).
+    This can be used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --project-domain <project-domain>
+
+    Domain the project belongs to (name or ID).
+    This can be used in case collisions between project names exist.
+
+    .. versionadded:: 3
+
 role remove
 -----------
 
@@ -116,8 +158,8 @@ Remove role from domain/project : user/group
 .. code:: bash
 
     os role remove
-        [--domain <domain> | --project <project]
-        [--user <user> | --group <group>]
+        --domain <domain> | --project <project> [--project-domain <project-domain>]
+        --user <user> [--user-domain <user-domain>] | --group <group> [--group-domain <group-domain>]
         <role>
 
 .. option:: --domain <domain>
@@ -140,6 +182,27 @@ Remove role from domain/project : user/group
 
     .. versionadded:: 3
 
+.. option:: --user-domain <user-domain>
+
+    Domain the user belongs to (name or ID).
+    This can be used in case collisions between user names exist.
+
+    .. versionadded:: 3
+
+.. option:: --group-domain <group-domain>
+
+    Domain the group belongs to (name or ID).
+    This can be used in case collisions between group names exist.
+
+    .. versionadded:: 3
+
+.. option:: --project-domain <project-domain>
+
+    Domain the project belongs to (name or ID).
+    This can be used in case collisions between project names exist.
+
+    .. versionadded:: 3
+
 .. describe:: <role>
 
     Role to remove (name or ID)
diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst
index 3455558..10ab306 100644
--- a/doc/source/command-objects/server.rst
+++ b/doc/source/command-objects/server.rst
@@ -67,7 +67,7 @@ Create a new server
         [--user-data <user-data>]
         [--availability-zone <zone-name>]
         [--block-device-mapping <dev-name=mapping> [...] ]
-        [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr> [...] ]
+        [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,v6-fixed-ip=ip-addr,port-id=port-uuid> [...] ]
         [--hint <key=value> [...] ]
         [--config-drive <value>|True ]
         [--min <count>]
@@ -115,9 +115,14 @@ Create a new server
 
     Map block devices; map is <id>:<type>:<size(GB)>:<delete_on_terminate> (optional extension)
 
-.. option:: --nic <nic-config-string>
+.. option:: --nic <net-id=net-uuid,v4-fixed-ip=ip-addr,v6-fixed-ip=ip-addr,port-id=port-uuid>
 
-    Specify NIC configuration (optional extension)
+    Create a NIC on the server. Specify option multiple times to create
+    multiple NICs. Either net-id or port-id must be provided, but not both.
+    net-id: attach NIC to network with this UUID,
+    port-id: attach NIC to port with this UUID,
+    v4-fixed-ip: IPv4 fixed address for NIC (optional),
+    v6-fixed-ip: IPv6 fixed address for NIC (optional).
 
 .. option:: --hint <key=value>
 
@@ -152,7 +157,11 @@ Delete server(s)
 .. code:: bash
 
     os server delete
-        <server> [<server> ...]
+        <server> [<server> ...] [--wait]
+
+.. option:: --wait
+
+    Wait for delete to complete
 
 .. describe:: <server>
 
diff --git a/doc/source/command-objects/service-provider.rst b/doc/source/command-objects/service-provider.rst
new file mode 100644
index 0000000..963493b
--- /dev/null
+++ b/doc/source/command-objects/service-provider.rst
@@ -0,0 +1,125 @@
+================
+service provider
+================
+
+Identity v3
+
+`Requires: OS-FEDERATION extension`
+
+service provider create
+-----------------------
+
+Create new service provider
+
+.. program:: service provider create
+.. code:: bash
+
+    os service provider create
+        [--description <description>]
+        [--enable | --disable]
+        --auth-url <auth-url>
+        --service-provider-url <sp-url>
+        <name>
+
+.. option:: --auth-url
+
+    Authentication URL of remote federated service provider (required)
+
+.. option:: --service-provider-url
+
+    A service URL where SAML assertions are being sent (required)
+
+.. option:: --description
+
+    New service provider description
+
+.. option:: --enable
+
+    Enable the service provider (default)
+
+.. option:: --disable
+
+    Disable the service provider
+
+.. describe:: <name>
+
+    New service provider name (must be unique)
+
+service provider delete
+-----------------------
+
+Delete service provider
+
+.. program:: service provider delete
+.. code:: bash
+
+    os service provider delete
+        <service-provider>
+
+.. describe:: <service-provider>
+
+    Service provider to delete
+
+service provider list
+---------------------
+
+List service providers
+
+.. program:: service provider list
+.. code:: bash
+
+    os service provider list
+
+service provider set
+--------------------
+
+Set service provider properties
+
+.. program:: service provider set
+.. code:: bash
+
+    os service provider set
+        [--enable | --disable]
+        [--description <description>]
+        [--auth-url <auth-url>]
+        [--service-provider-url <sp-url>]
+        <service-provider>
+
+.. option:: --service-provider-url
+
+    New service provider URL, where SAML assertions are sent
+
+.. option:: --auth-url
+
+    New Authentication URL of remote federated service provider
+
+.. option:: --description
+
+    New service provider description
+
+.. option:: --enable
+
+    Enable the service provider
+
+.. option:: --disable
+
+    Disable the service provider
+
+.. describe:: <service-provider>
+
+    Service provider to modify
+
+service provider show
+---------------------
+
+Display service provider details
+
+.. program:: service provider show
+.. code:: bash
+
+    os service provider show
+        <service-provider>
+
+.. describe:: <service-provider>
+
+    Service provider to display
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 42d041a..b52d945 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -111,6 +111,7 @@ referring to both Compute and Volume quotas.
 * ``server``: (**Compute**) virtual machine instance
 * ``server image``: (**Compute**) saved server disk image
 * ``service``: (**Identity**) a cloud service
+* ``service provider``: (**Identity**) a resource that consumes assertions from an ``identity provider``
 * ``snapshot``: (**Volume**) a point-in-time copy of a volume
 * ``token``: (**Identity**) a bearer token managed by Identity service
 * ``usage``: (**Compute**) display host resources being consumed
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
new file mode 100644
index 0000000..e371e50
--- /dev/null
+++ b/doc/source/configuration.rst
@@ -0,0 +1,133 @@
+=============
+Configuration
+=============
+
+OpenStackClient is primarily configured using command line options and environment
+variables.  Most of those settings can also be placed into a configuration file to
+simplify managing multiple cloud configurations.
+
+There is a relationship between the global options, environment variables and
+keywords used in the configuration files that should make translation between
+these three areas simple.
+
+Most global options have a corresponding environment variable that may also be
+used to set the value. If both are present, the command-line option takes priority.
+The environment variable names are derived from the option name by dropping the
+leading dashes (--), converting each embedded dash (-) to an underscore (_), and
+converting to upper case.
+
+The keyword names in the configurations files are derived from the global option
+names by dropping the ``--os-`` prefix if present.
+
+Global Options
+--------------
+
+The :doc:`openstack manpage <man/openstack>` lists all of the global
+options recognized by OpenStackClient and the default authentication plugins.
+
+Environment Variables
+---------------------
+
+The :doc:`openstack manpage <man/openstack>` also lists all of the
+environment variables recognized by OpenStackClient and the default
+authentication plugins.
+
+Configuration Files
+-------------------
+
+clouds.yaml
+~~~~~~~~~~~
+
+:file:`clouds.yaml` is a configuration file that contains everything needed
+to connect to one or more clouds.  It may contain private information and
+is generally considered private to a user.
+
+OpenStackClient looks for a file called :file:`clouds.yaml` in the following
+locations:
+
+* current directory
+* :file:`~/.config/openstack`
+* :file:`/etc/openstack`
+
+The first file found wins.
+
+The keys match the :program:`openstack` global options but without the
+``--os-`` prefix.
+
+::
+
+    clouds:
+      devstack:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: demo
+          username: demo
+          password: 0penstack
+        region_name: RegionOne
+      ds-admin:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: admin
+          username: admin
+          password: 0penstack
+        region_name: RegionOne
+      infra:
+        cloud: rackspace
+        auth:
+          project_id: 275610
+          username: openstack
+          password: xyzpdq!lazydog
+        region_name: DFW,ORD,IAD
+
+In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken
+from :file:`clouds-public.yaml` (see below).
+
+The first two entries are for two of the default users of the same DevStack
+cloud.
+
+The third entry is for a Rackspace Cloud Servers account.  It is equivalent
+to the following options if the ``rackspace`` entry in :file:`clouds-public.yaml`
+(below) is present:
+
+::
+
+    --os-auth-url https://identity.api.rackspacecloud.com/v2.0/
+    --os-project-id 275610
+    --os-username openstack
+    --os-password xyzpdq!lazydog
+    --os-region-name DFW
+
+and can be selected on the command line::
+
+    openstack --os-cloud infra server list
+
+Note that multiple regions are listed in the ``rackspace`` entry.  An otherwise
+identical configuration is created for each region.  If ``-os-region-name`` is not
+specified on the command line, the first region in the list is used by default.
+
+clouds-public.yaml
+~~~~~~~~~~~~~~~~~~
+
+:file:`clouds-public.yaml` is a configuration file that is intended to contain
+public information about clouds that are common across a large number of users.
+The idea is that :file:`clouds-public.yaml` could easily be shared among users
+to simplify public could configuration.
+
+Similar to :file:`clouds.yaml`, OpenStackClient looks for
+:file:`clouds-public.yaml` in the following locations:
+
+* current directory
+* :file:`~/.config/openstack`
+* :file:`/etc/openstack`
+
+The first file found wins.
+
+The keys here are referenced in :file:`clouds.yaml` ``cloud`` keys.  Anything
+that appears in :file:`clouds.yaml`
+
+::
+
+    public-clouds:
+      rackspace:
+        auth:
+          auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 60a43d4..a3bc58e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,10 +13,12 @@ Contents:
 
    command-list
    commands
+   configuration
    plugins
    authentication
    interactive
    humaninterfaceguide
+   backwards-incompatible
    releases
    man/openstack
 
@@ -47,6 +49,7 @@ contributions.  The code is hosted `on OpenStack's Git server`_. `Bug reports`_
 and `blueprints`_ may be submitted to the :code:`python-openstackclient` project
 on `Launchpad`_.  Code may be submitted to the
 :code:`openstack/python-openstackclient` project using `Gerrit`_.
+Developers may also be found in the `IRC channel`_ ``#openstack-sdks``.
 
 .. _`on OpenStack's Git server`: https://git.openstack.org/cgit/openstack/python-openstackclient/tree
 .. _Launchpad: https://launchpad.net/python-openstackclient
@@ -55,6 +58,7 @@ on `Launchpad`_.  Code may be submitted to the
 .. _blueprints: https://blueprints.launchpad.net/python-openstackclient
 .. _PyPi: https://pypi.python.org/pypi/python-openstackclient
 .. _tarball: http://tarballs.openstack.org/python-openstackclient
+.. _IRC channel: https://wiki.openstack.org/wiki/IRC
 
 Indices and Tables
 ==================
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index a6de54d..6d6dce4 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/man/openstack.rst
@@ -4,6 +4,7 @@
 
 OpenStack Command Line
 
+
 SYNOPSIS
 ========
 
@@ -57,8 +58,15 @@ OPTIONS
 
 :program:`openstack` recognizes the following global options:
 
-:option:`--os-auth-plugin` <auth-plugin>
-    The authentication plugin to use when connecting to the Identity service. If this option is not set, :program:`openstack` will attempt to guess the authentication method to use based on the other options.
+:option:`--os-cloud` <cloud-name>
+    :program:`openstack` will look for a ``clouds.yaml`` file that contains
+    a cloud configuration to use for authentication.  See CLOUD CONFIGURATION
+    below for more information.
+
+:option:`--os-auth-type` <auth-type>
+    The authentication plugin type to use when connecting to the Identity service.
+    If this option is not set, :program:`openstack` will attempt to guess the
+    authentication method to use based on the other options.
     If this option is set, its version must match :option:`--os-identity-api-version` 
 
 :option:`--os-auth-url` <auth-url>
@@ -156,6 +164,81 @@ Command Actions
 
 The actions used by OpenStackClient are defined with specific meaning to provide a consistent behavior for each object.  Some actions have logical opposite actions, and those pairs will always match for any object that uses them.
 
+
+CLOUD CONFIGURATION
+===================
+
+Working with multiple clouds can be simplified by keeping the configuration
+information for those clouds in a local file.  :program:`openstack` supports
+using a ``clouds.yaml`` configuration file.
+
+Config Files
+------------
+
+:program:`openstack` will look for a file called clouds.yaml in the following
+locations:
+
+* Current Directory
+* ~/.config/openstack
+* /etc/openstack
+
+The first file found wins.
+
+The keys match the :program:`openstack` global options but without the
+``--os-`` prefix:
+
+::
+
+    clouds:
+      devstack:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: demo
+          username: demo
+          password: 0penstack
+        region_name: RegionOne
+      ds-admin:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: admin
+          username: admin
+          password: 0penstack
+        region_name: RegionOne
+      infra:
+        cloud: rackspace
+        auth:
+          project_id: 275610
+          username: openstack
+          password: xyzpdq!lazydog
+        region_name: DFW,ORD,IAD
+
+In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken
+from :file:`clouds-public.yaml`:
+
+::
+
+    public-clouds:
+      rackspace:
+        auth:
+          auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
+
+Authentication Settings
+-----------------------
+
+OpenStackClient uses the Keystone authentication plugins so the required
+auth settings are not always known until the authentication type is
+selected.  :program:`openstack` will attempt to detect a couple of common
+auth types based on the arguments passed in or found in the configuration
+file, but if those are incomplete it may be impossible to know which
+auth type is intended.  The :option:`--os-auth-type` option can always be
+used to force a specific type.
+
+When :option:`--os-token` and :option:`--os-url` are both present the
+``token_endpoint`` auth type is selected automatically.  If
+:option:`--os-auth-url` and :option:`--os-username` are present ``password``
+auth type is selected.
+
+
 NOTES
 =====
 
@@ -192,6 +275,15 @@ Create a new image::
 FILES
 =====
 
+:file:`~/.config/openstack/clouds.yaml`
+    Configuration file used by the :option:`--os-cloud` global option.
+
+:file:`~/.config/openstack/clouds-public.yaml`
+    Configuration file containing public cloud provider information such as
+    authentication URLs and service definitions.  The contents of this file
+    should be public and sharable.  ``clouds.yaml`` may contain references
+    to clouds defined here as shortcuts.
+
 :file:`~/.openstack`
     Placeholder for future local state directory.  This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it.  Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable.
 
@@ -201,6 +293,9 @@ ENVIRONMENT VARIABLES
 
 The following environment variables can be set to alter the behaviour of :program:`openstack`.  Most of them have corresponding command-line options that take precedence if set.
 
+:envvar:`OS_CLOUD`
+    The name of a cloud configuration in ``clouds.yaml``.
+
 :envvar:`OS_AUTH_PLUGIN`
     The authentication plugin to use when connecting to the Identity service, its version must match the Identity API version 
 
diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index 0635f29..d603e10 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -7,8 +7,41 @@ properly installed for OSC to find and use it.  It utilizes the
 ``setuptools`` entry points mechanism to advertise to OSC the
 plugin module and supported commands.
 
+Adoption
+========
+
+OpenStackClient promises to provide first class support for the following
+OpenStack services: Compute, Identity, Image, Storage, Volume and Network.
+These services are considered essential to any OpenStack deployment.
+
+Other OpenStack services, such as Orchestration or Telemetry may create an
+OpenStackClient plugin. The source code will not be hosted by
+OpenStackClient.
+
+The following is a list of projects and their status as an OpenStackClient
+plugin.
+
+=============================  ======================================
+   project                     notes
+=============================  ======================================
+python-barbicanclient          n/a
+python-ceilometerclient        n/a
+python-congressclient          using only OpenStackClient
+python-designateclient         n/a
+python-heatclient              plans on creating plugins
+python-ironicclient            patch in progress (https://review.openstack.org/#/c/171672/)
+python-magnumclient            sent note on ML about creating a plugin
+python-manilaclient            n/a
+python-mistralclient           n/a
+python-muranoclient            n/a
+python-saharaclient            n/a
+python-troveclient             n/a
+python-tuskarclient            using OpenStackClient and their own shell
+python-zaqarclient             using only OpenStackClient
+=============================  ======================================
+
 Implementation
---------------
+==============
 
 Plugins are discovered by enumerating the entry points
 found under :py:mod:`openstack.cli.extension` and initializing the specified
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
index 98aea30..c2694c0 100644
--- a/doc/source/releases.rst
+++ b/doc/source/releases.rst
@@ -2,6 +2,132 @@
 Release Notes
 =============
 
+1.5.0 (16 Jun 2015)
+===================
+
+* openstack 'ListEC2Creds' object has no attribute 'determine_ec2_user'
+  Bug `1465561 <https://bugs.launchpad.net/bugs/1465561>`_
+
+1.4.0 (04 Jun 2015)
+===================
+
+* AttributeError: 'Client' object has no attribute 'ec2'
+  Bug `1236326 <https://bugs.launchpad.net/bugs/1236326>`_
+
+* ``--insecure`` is ignored if ``OS_CACERT`` env var is set
+  Bug `1447784 <https://bugs.launchpad.net/bugs/1447784>`_
+
+* ``security group list`` always uses identity admin endpoint
+  Bug `1459629 <https://bugs.launchpad.net/bugs/1459629>`_
+
+* Race failure to delete security group
+  Bug `1460112 <https://bugs.launchpad.net/bugs/1460112>`_
+
+* v3 project set is missing ``--domain`` argument
+  Bug `1460122 <https://bugs.launchpad.net/bugs/1460122>`_
+
+* Project create is missing ``--parent`` argument in doc
+  Bug `1460256 <https://bugs.launchpad.net/bugs/1460256>`_
+
+* v3 ``role add`` is missing domain scope arguments in doc
+  Bug `1460296 <https://bugs.launchpad.net/bugs/1460296>`_
+
+* Cannot force v2password auth plugin
+  Bug `1460369 <https://bugs.launchpad.net/bugs/1460369>`_
+
+1.3.0 (27 May 2015)
+===================
+
+* Need to specify domain with role list
+  Bug `1421328 <https://bugs.launchpad.net/bugs/1421328>`_
+
+* Add support for keystone service providers
+  Bug `1435962 <https://bugs.launchpad.net/bugs/1435962>`_
+
+* Can't update disk_format and container_format of image
+  Bug `1446362 <https://bugs.launchpad.net/bugs/1446362>`_
+
+* Openstack --os-image-api-version 2 image show <image_id> fails
+  Bug `1450829 <https://bugs.launchpad.net/bugs/1450829>`_
+
+* The insecure option is ignored for command line options and OCC
+  Bug `1450855 <https://bugs.launchpad.net/bugs/1450855>`_
+
+* Delete security group rule broken
+  Bug `1450872 <https://bugs.launchpad.net/bugs/1450872>`_
+
+* Quota set sends invalid messages
+  Bug `1451640 <https://bugs.launchpad.net/bugs/1451640>`_
+
+* Keystone Access Log logs "python-keystoneclient" as User-Agent even when request is made by openstack client
+  Bug `1453995 <https://bugs.launchpad.net/bugs/1453995>`_
+
+* Client error while rescuing an instance
+  Bug `1457983 <https://bugs.launchpad.net/bugs/1457983>`_
+
+
+1.2.0 (30 Apr 2015)
+===================
+
+* Fix error in ``security group create`` command when ``--description`` is not
+  supplied.
+  Bug `1434172 <https://bugs.launchpad.net/bugs/1434172>`_
+
+* Correct ``image list`` pagination handling, all images are now correctly returned.
+  Bug `1443089 <https://bugs.launchpad.net/bugs/1443089>`_
+
+* Do not require ``--dst-port`` option with ``security group rule create`` when
+  ``--proto ICMP`` is selected.
+  Bug `1443963 <https://bugs.launchpad.net/bugs/1443963>`_
+
+* Correctly pass ``--location`` arguemnt in ``image create`` command.
+  Bug `1445460 <https://bugs.launchpad.net/bugs/1445460>`_
+
+* Correctly handle use of ``role`` commands for project admins.  Using IDs will
+  work for project admins even when names will not due to non-admin contraints.
+  Bug `1445528 <https://bugs.launchpad.net/bugs/1445528>`_
+
+* Correctly exit with an error when authentication can not be completed.
+  Bug `1444640 <https://bugs.launchpad.net/bugs/1444640>`_
+
+* Fix ``backup create`` to correctly use the ``--container`` value if supplied.
+  Bug `1446751 <https://bugs.launchpad.net/bugs/1446751>`_
+
+* Document the backward-compatibility-breaking changes in
+  :doc:`backwards-incompatibile`.
+  Bug `1406470 <https://bugs.launchpad.net/bugs/1406470>`_
+
+* Add `--parent`` option to `projct create` command.
+
+
+1.1.0 (21 Apr 2015)
+===================
+
+* Add global ``--os-cloud`` option to select from a list of cloud configurations.
+  See :doc:`configuration` for more details.
+
+* Fix global ``--timing`` option operation.
+  Bug `1402577 <https://bugs.launchpad.net/bugs/1402577>`_
+
+* Add ``flavor set`` and ``flavor unset`` commands.
+  Bug `1434137 <https://bugs.launchpad.net/bugs/1434137>`_
+
+* Add ``--domain`` and ``--project`` options to ``network create`` command.
+  Bug `1435640 <https://bugs.launchpad.net/bugs/1435640>`_
+
+* Add ``--volume-type`` option to ``quota set`` command.
+  Bug `1438377 <https://bugs.launchpad.net/bugs/1438377>`_
+
+* Add ``--domain`` and ``--project`` options to ``limits show`` command.
+  Bug `1438379 <https://bugs.launchpad.net/bugs/1438379>`_
+
+* Improve ``--nic`` option help for ``server create`` command.
+  Bug `1444685 <https://bugs.launchpad.net/bugs/1444685>`_
+
+* Add ``--remote-id`` and ``--remote-id-file`` options to
+  ``identity provider create`` and ``identity provider set`` commands.
+
+
 1.0.3 (10 Mar 2015)
 ===================
author	Corey Bryant <corey.bryant@canonical.com>	2015-06-22 16:07:31 +0100
committer	git-ubuntu importer <ubuntu-devel-discuss@lists.ubuntu.com>	2015-06-22 22:10:41 +0000
commit	f3e023ac0edd14f64b870dd0c81152248d26870e (patch)
tree	05d8a27edc3836757a1c8edddc5e7568e64ed0a9 /doc
parent	ae5b9e8ef6e165eb7cfa9b6e447a62f226a3bee9 (diff)