OpenStack Client Configuration Library

2.3.0 · maintenance · verified Thu Apr 16

os-client-config is a Python library designed for standardizing OpenStack client configuration. It aggregates configuration data from environment variables (prefixed with `OS_`) and `clouds.yaml` files, providing a consistent interface for OpenStack applications. The current version is 2.3.0. While still maintained, it is largely superseded by `openstacksdk` for new development.

Common errors

```
Building from tar will have missing files, such as defaults.json, schema.json and so on.
```
cause When building `os-client-config` from a tarball (e.g., using `pbr`), certain JSON configuration files required by the library might be omitted from the distribution.

fix Avoid building from tarball releases directly if you encounter this issue. The recommended workaround is to build from the git package and ensure proper tagging, or rely on official PyPI releases which are pre-built correctly.
```
Error getting OpenStack cloud config: The cloud 'mycloud' was not found.
```
cause This error occurs when the specified cloud name (`'mycloud'` in the example) cannot be found in any of the configured sources (environment variables, `clouds.yaml` files). This could be due to a missing `OS_CLOUD` environment variable, an incorrectly named cloud in `clouds.yaml`, or `clouds.yaml` not being found in expected locations.

fix Verify that either the `OS_CLOUD` environment variable is set to a valid cloud name, or that a `clouds.yaml` file exists in one of the standard locations (`.`, `~/.config/openstack`, `/etc/openstack`) and contains a definition for the cloud name you are trying to access. Ensure the cloud name in your code matches the configuration.

Warnings

breaking The `os-client-config` library has been largely superseded by `openstacksdk`. While `os-client-config` will continue to exist, OpenStack strongly recommends migrating to `openstacksdk` for all new projects and existing ones where feasible, as `openstacksdk` provides a more comprehensive and actively developed client experience.
Fix: Migrate your application to use `openstacksdk` directly. Install with `pip install openstacksdk` and update your import paths and client instantiation logic.
gotcha When combining `clouds.yaml` (public configuration) and `secrets.yaml` (sensitive data), issues can arise if the number or names of clouds defined in each file do not perfectly match. This can lead to incomplete cloud configurations, with essential parameters like `auth_url` missing for clouds only partially defined.
Fix: Ensure that all clouds you intend to use are consistently defined across both `clouds.yaml` and `secrets.yaml` files, especially if using OpenStack dynamic inventories or similar tools.
deprecated `os-client-config` does not provide backward compatibility for older, service-specific environment variables such as `NOVA_USERNAME`. It strictly honors the generic `OS_*` variables.
Fix: Use generic `OS_USERNAME` and other `OS_*` prefixed environment variables. Refer to the OpenStack official documentation for the correct, current environment variable names.

Install

pip install os-client-config Install latest version

Imports

OpenStackConfig

from os_client_config import OpenStackConfig

Quickstart

This quickstart demonstrates how to initialize `OpenStackConfig` and retrieve the configuration for a named OpenStack cloud. The library automatically looks for configuration in environment variables (`OS_*`) or `clouds.yaml` files located in the current directory, `~/.config/openstack`, or `/etc/openstack`.

import os
from os_client_config import OpenStackConfig

# Configure a cloud either via environment variables (OS_CLOUD, OS_AUTH_URL, etc.)
# or a clouds.yaml file (e.g., in ~/.config/openstack/clouds.yaml)

# Example: Get configuration for a cloud named 'mycloud'
# Ensure OS_CLOUD is set or 'mycloud' is defined in clouds.yaml
cloud_name = os.environ.get('OS_CLOUD', 'mycloud')

try:
    # Initialize the config object
    config = OpenStackConfig()

    # Get the configuration for a specific cloud
    cloud = config.get_one_cloud(cloud_name)

    # Access configuration details
    print(f"Cloud name: {cloud.name}")
    print(f"Region: {cloud.region_name}")
    print(f"Auth URL: {cloud.auth['auth_url']}")

    # Example: Print a few more details (be cautious with sensitive info)
    if 'username' in cloud.auth:
        print(f"Username: {cloud.auth['username']}")
    
except Exception as e:
    print(f"Error getting OpenStack cloud config: {e}")
    print("Please ensure 'OS_CLOUD' environment variable is set or 'clouds.yaml' is configured correctly.")

view raw JSON →