# OpenStack

The official [OpenStack Keystone](<https://docs.openstack.org/keystone/latest/>) endpoint is available at:

- [`https://keystone.cloud.syseleven.net:5000/v3`](<https://keystone.cloud.syseleven.net:5000/v3>)

> [!NOTE]
>
> **IAM Specifics**
>
> **Users**:
>
> - Authenticate via `OIDC`
> - Log in using a browser with your 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

> [!TIP]
>
> **OpenStack Environment Variables**
>
> Remember to reset your OpenStack environment variables if needed:
>
> ```bash
> 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](<https://astral.sh/>) [`uv`](<https://github.com/astral-sh/uv>) package manager for installing Python and managing virtual environments.

Head to [the official installation instructions](<https://docs.astral.sh/uv/getting-started/installation/>) to install `uv`.

Next, install the `openstackclient` as a [`uv` tool](<https://docs.astral.sh/uv/concepts/tools/>) and include our library [`openstack-s11auth`](<https://pypi.org/project/openstack-s11auth/>).

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

> [!WARNING]
>
> **netifaces Error**
>
> If you're seeing `netifaces` errors on Linux, please instruct `uv` to use `Python 3.9`:
>
> ```bash
> 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.

> [!TIP]
>
> **`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.

> [!WARNING]
>
> **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`

> [!TIP]
>
> **Obtain `clouds.yaml` from the Dashboard**
>
> You can obtain your `clouds.yaml` file by using the [Dashboard](<https://documentation.syseleven.de/en/products/iam/usage/service-accounts/index.md>).

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

#### `clouds.yaml` for User Authentication

```yaml
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:

```bash
export OS_CLOUD=SYS11_USER_AUTH_DUS2
```

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

```bash
openstack project list --long
```

> [!TIP]
>
> **Pro Tip**
>
> Using `clouds.yaml` lets you switch between OpenStack environments by changing the `OS_CLOUD` variable. This is essential when managing projects across regions.

#### `clouds.yaml` for Service Account Authentication

```yaml
##############################################################################################################################################
# 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

```bash
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

> [!NOTE]
>
> **Service Account Credentials Required**
>
> To use a service account, please [first create a service account](<https://documentation.syseleven.de/en/products/iam/usage/service-accounts/#create-service-account>).

```bash
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.

> [!NOTE]
>
> **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 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, see our [How-To Guide](<https://documentation.syseleven.de/en/how-to/openstack/openstack-terraform-example/index.md>) or browse the [terraform-examples repository](<https://github.com/syseleven/terraform-examples>) for sample configurations and best practices (please note that you would have to adapt the examples to the new IAM and regions DUS2/HAM1).

When using Terraform with OpenStack, you must use Service Account with the `OpenStack Editor` permission, to authenticate. You can find always browse the [provider documentation](<https://registry.terraform.io/providers/terraform-provider-openstack/openstack/latest/docs>) for the latest information.
