From 6e7013954d4119c91345a5b83b9675c4be62a11d Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Tue, 3 Mar 2015 23:12:07 -0600 Subject: [PATCH] Begin documenting --os-cloud Change-Id: Id2e98ac5601840f6d380cabcd578f1a6d6d9b245 --- doc/source/authentication.rst | 7 +- doc/source/configuration.rst | 133 ++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + doc/source/man/openstack.rst | 99 ++++++++++++++++++++++++- 4 files changed, 236 insertions(+), 4 deletions(-) create mode 100644 doc/source/configuration.rst 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 ` lists all of the global +options recognized by OpenStackClient and the default authentication plugins. + +Environment Variables +--------------------- + +The :doc:`openstack manpage ` 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` - 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` + :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` + 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` @@ -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