Overview

The TL;DR for Client Cloud Configuration is take a global public cloud configuration file, add to it local clouds and/or public cloud authentication and region details and use them with a single command line option or environment variable and forget sourcing many openrc-like files.

clouds.yaml

It all starts with the clouds.yaml file that contains your cloud configuration details. This is really the only file required to use --os-cloud and defines its available arguments. OSC searches the following directories for clouds.yaml and uses only the first one it finds:

* the current directory
* ``~/.config/openstack``, aka ``$XDG_CONFIG_HOME/openstack``
* ``/etc/openstack``

~/.config is a well-known directory defined by the freedesktop.org XDG Base Directory Specification. If XDG_CONFIG_HOME is defined, it will be used in place of ~/.config.

clouds.yaml defines a list of clouds, the key for each cloud definition is shockingly the argument used with the --os-cloud option. Each cloud definition is made up of a list of keys that correspond to OSC's global options. One special item in this list is auth, which contains all of the authentication-related options. A bare-minimum clouds.yaml that works with a default DevStack installation (using Identity v2) looks like this:

clouds:
  devstack:
    auth:
      auth_url: http://127.0.0.1:35357/
      project_name: demo
      username: demo
      password: 0penstack
    region_name: RegionOne

With that configuration, you can skip sourcing openrc and do this:

openstack --os-cloud devstack token issue

to get a token from the running cloud.

clouds-public.yaml

Duplicating the configuration for public clouds (or private clouds within an organization) gets tedious, thus the motivation for clouds-public.yaml. The search path is the same as for clouds.yaml, in fact it is basically the same file except that the top-level key is public-clouds.

I should also note that a small set of public OpenStack clouds is also built-in to OSC so they can be referenced automatically. Here is an sample of the current built-in configuration:

public-clouds:
    hp:
        auth:
            auth_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0
        region_name: region-b.geo-1
        dns_service_type: 'hpext:dns'
        image_api_version: 1
        image_format: qcow2
    rackspace:
        auth:
            auth_url: https://identity.api.rackspacecloud.com/v2.0/
        database_service_type: 'rax:database'
        compute_service_name: cloudServersOpenStack
        image_api_version: 2
        image_api_use_tasks: True
        image_format: vhd
    dreamhost:
        auth:
            auth_url: https://keystone.dream.io/v2.0
        region_name: RegionOne
        image_api_version: 2
        image_format: raw

Note that not all of those configuration options are recognized by OSC yet.

With the above file, a clouds.yaml file that utilized it might look like this:

clouds:
    rax:
        cloud: rackspace
        auth:
            project_id: 123456
            username: joe-stacker
            password: 0penstack
        region_name: DFW

The cloud key selects the rackspace definition from the clouds-public.yaml file. The auth_url is automatically inherited from the rackspace definition. With those definitions, all that is required is the following:

openstack --os-cloud rax server list

or for those who still want to hang on to the old way, with an environment variable:

OS_CLOUD=rax openstack server list