Skip to content

API Access — OpenStack

The official OpenStack Keystone endpoint is available at:

SysEleven IAM Specifics

Users:

  • Authenticate via OIDC
  • Log in using a browser with your SysEleven credentials
  • Authenticate against OpenStack via JWT using the openstack-s11auth plugin

Service Accounts:

  • Persistent machine identity, can have multiple credentials
  • Organization-bound entity with similar permission set to users
  • Authenticate via Bearer tokens
  • Authenticate against OpenStack as application credentials

OpenStack Setup

OpenStack Environment Variables

Remember to reset your OpenStack environment variables if needed: 

unset $(set | grep OS_ | sed 's/=.*//')
This command will unset all variables starting with OS_.

To begin using OpenStack, you need to install the OpenStack client, which itself requires Python. We recommend using astral's uv package manager for installing Python and managing virtual environments.

Head to the official installation instructions to install uv.

Next, install the openstackclient as a uv tool and include the SysEleven library openstack-s11auth.

uv tool install \
    --with openstack-s11auth \
    --with python-manilaclient \
    --with python-barbicanclient \
    --with python-designateclient \
    --with python-octaviaclient \
    --upgrade python-openstackclient

netifaces Error

If you're seeing netifaces errors on Linux, please instruct uv to use Python 3.9:

uv tool install \
    --python=3.9 \
    --with openstack-s11auth \
    --with python-manilaclient \
    --with python-barbicanclient \
    --with python-designateclient \
    --with python-octaviaclient \
    --upgrade python-openstackclient

Use openstack --help to verify that the installation was successful.

uv benefits

  • uv is a modern and efficient package manager for Python.
  • By using uv tool to install the OpenStack client, you can use openstack from your CLI, with all dependencies being constrained to a specific virtual environment. No more venv hassle!
  • 💡 For an ephemeral setup, run e.g. uvx --with openstack-s11auth --from python-openstackclient openstack --os-auth-url="https://keystone.cloud.syseleven.net:5000/v3" --os-auth-type="v3s11" project list --long to list your projects.

Be careful about conflicts with pip

If you have previously installed the OpenStack client via pip, please remove it before installing via uv to avoid conflicts. If you have existing Python installations, uv will simply use it, if not uv will even manage Python for you.

Of course, if you prefer to use other methods for managing your Python environment, you can do so.

Authentication

You can authenticate against OpenStack as a user, or a service account.

Using clouds.yaml

Obtain clouds.yaml from the SysEleven Dashboard

You can obtain your clouds.yaml file by using the SysEleven Dashboard.

Create a file at ~/.config/openstack/clouds.yaml with the following structure:

clouds.yaml for User Authentication

clouds:
  SYS11_USER_AUTH_HAM1:
    auth:
      auth_url: "https://keystone.cloud.syseleven.net:5000/v3"
      # project_id: "your_project_id" # if you want a default project id, set it here. Else, `export OS_PROJECT_ID=<your-project-id>` before running project-scope openstack commands
    region_name: "ham1"
    auth_type: "v3s11"

  SYS11_USER_AUTH_DUS2:
    auth:
      auth_url: "https://keystone.cloud.syseleven.net:5000/v3"
      # project_id: "your_project_id" # if you want a default project id, set it here. Else, `export OS_PROJECT_ID=<your-project-id>` before running project-scope openstack commands
    region_name: "dus2"
    auth_type: "v3s11"

Replace the placeholders with your actual credentials and project information.

Now, to use a specific configuration, set the OS_CLOUD environment variable:

export OS_CLOUD=SYS11_USER_AUTH_DUS2

Now you can use the openstack command without additional authentication steps:

openstack project list --long

Pro Tip

Using clouds.yaml allows you to easily switch between different OpenStack environments by changing the OS_CLOUD variable. This is especially useful when working with multiple projects or regions.

clouds.yaml for Service Account Authentication

##############################################################################################################################################
# This file was generated by Alloy Dashboard (2025-01-01T00:00:00.000Z) for the SysEleven Service Account 00000000-0000-0000-0000-000000000000
##############################################################################################################################################
#
# The entries under clouds correspond to an auth, project and region context.
# In this config, the keys follow the naming scheme <project_name>_<region_name>.
#
# You can add these entries to your existing clouds.yaml at ~/.config/openstack/clouds.yaml.
# Tools like python-openstackclient or the OpenStack Terraform Provider will read this file
# and use its information to authenticate against OpenStack.
#
# Valid directories that clients will search for clouds.yaml include:
# - current directory
# - ~/.config/openstack
# - /etc/openstack
#
# In order to select a specific configuration (auth, project and region), set the
# environment variable OS_CLOUD to the respective key, e.g. syseleven_project_dus2.
#

clouds:
  syseleven_project_dus2:
    auth_type: v3applicationcredential
    auth:
      auth_url: https://keystone.cloud.syseleven.net:5000/v3
      application_credential_id: s11auth:<project_id>
      application_credential_secret: s11_orgsa_<service_account_uuid>_<service_account_secret>
      project_id: <project_id>
    region_name: dus2 # or ham1
    interface: public
    identity_api_version: 3

Using Environment Variables

If you prefer, you can also use environment variables directly.

Environment Variables for User Authentication

unset $(set | grep OS_ | sed 's/=.*//')
export KEYSTONE_ORIGIN="https://keystone.cloud.syseleven.net:5000"
export OS_AUTH_URL="$KEYSTONE_ORIGIN/v3"
export OS_REGION_NAME=dus2 # or ham1
export OS_AUTH_TYPE=v3s11 # this requires the openstack-s11auth plugin to be installed
openstack project list --long

Environment Variables for Service Account Authentication

Service Account Credentials Required

To use a service account, please first create a service account.

unset HISTFILE
unset $(set | grep OS_ | sed 's/=.*//')
export KEYSTONE_ORIGIN="https://keystone.cloud.syseleven.net:5000"
export OS_AUTH_URL="$KEYSTONE_ORIGIN/v3"
export OS_REGION_NAME=dus2 # or ham1
export OS_AUTH_TYPE=v3applicationcredential
export OS_PROJECT_ID=c45fcc2570784820874b3f3657c8d36c # If you want to change the project your service account authenticates against, change this variable.
export OS_APPLICATION_CREDENTIAL_ID="s11auth:${PROJECT_ID}" # Service Accounts require the PROJECT_ID as a suffix, as not all clients respect OS_PROJECT_ID.
export OS_APPLICATION_CREDENTIAL_SECRET=s11_orgsa_<service_account_uuid>_<service_account_secret>
openstack network list

After setting these environment variables, you can use the openstack command-line tool to interact with your OpenStack environment.

Not seeing all projects?

When using the openstack project list command, you may notice that not all projects you have access to are immediately visible. This is because the OpenStack CLI only shows projects that have been previously accessed through our web interface. This behavior is due to the way our system integrates OpenStack with our Identity and Access Management (IAM) service.

Here's what you need to know:

  1. Projects become visible in the CLI after you've selected them at least once in the web interface.
  2. This process ensures that the necessary configurations are set up in Keystone (OpenStack's identity service) for each project you access. Note that you have access to the project, even if it may not yet be visible in the CLI. The SysEleven IAM is the leading system for all cloud services.
  3. We're actively working on improving this experience to make all your accessible projects visible in the CLI without requiring prior web interface interaction.

If you don't see a project you expect to have access to, try selecting it in the web interface first, then run the openstack project list command again. This should make the project visible in your CLI output.

We appreciate your understanding as we work to enhance this functionality and provide a more seamless experience across all interfaces.

Using Terraform with OpenStack

To use Terraform with OpenStack, refer to our Howto Guide or browse the terraform-examples repository for sample configurations and best practices (please note that you would have to adapt the examples to the new SysEleven IAM and regions DUS2/HAM1).

When using Terraform with SysEleven OpenStack, you must use Service Account with the OpenStack Editor permission, to authenticate. You can find always browse the provider documentation for the latest information.