openstack/python-openstackclient
Code Issues Proposed changes

Merge "Begin documenting --os-cloud"

Browse Source
This commit is contained in:
Jenkins 2015-04-19 15:16:42 +00:00 committed by Gerrit Code Review
commit 46d9fa1080
4 changed files with 236 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/source/authentication.rst
View File

@ -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

133
doc/source/configuration.rst Normal file
View File

@ -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/'

1
doc/source/index.rst
View File

@ -13,6 +13,7 @@ Contents:
command-list
commands
configuration
plugins
authentication
interactive

99
doc/source/man/openstack.rst
View File

@ -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