Merge "Begin documenting --os-cloud"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
46d9fa1080
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/'
|
||||
|
|
@ -13,6 +13,7 @@ Contents:
|
|||
|
||||
command-list
|
||||
commands
|
||||
configuration
|
||||
plugins
|
||||
authentication
|
||||
interactive
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue