diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst
index fd48a0312a..bf23b66a01 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
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
new file mode 100644
index 0000000000..e371e50448
--- /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 60a43d45be..7258a7b4cc 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,6 +13,7 @@ Contents:
command-list
commands
+ configuration
plugins
authentication
interactive
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index a6de54db09..6d6dce4479 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