> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenStack

> Connect OpenStack to CloudThinker for visibility into servers, volumes, networks, images, and quotas, with approval-gated changes

Connect your OpenStack cloud to let CloudThinker agents inspect servers, volumes, networks, images, flavors, and quotas in one project, and make changes after you approve them. OpenStack authenticates with a **Keystone user name and password**, scoped to one project and one region.

## Prerequisites

* An **OpenStack cloud** whose Keystone (Identity) v3 address CloudThinker can reach. Use an `https` address.
* A **dedicated Keystone user** with a role on the project you want inspected. See [Required permissions](#required-permissions).
* The **project name**, the **domain** names of the user and the project, and the **region**.

<Info>
  CloudThinker supports one OpenStack connection per workspace, and each connection covers one project in one region. Federated sign-in and application credentials are not supported; the connection uses a user name and password.
</Info>

## Setup

<Steps>
  <Step title="Find your sign-in values">
    OpenStack's own documentation says that before you issue client commands you "must download and source the openrc file" for your project. Open that file, or ask your cloud administrator, for the authentication URL, project name, user name, domain names, and region.
  </Step>

  <Step title="Create or choose a Keystone user">
    Use a dedicated user and give it a role on the project. A `reader` role is the least-privilege start.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → OpenStack** and enter the fields in [Connection details](#connection-details). Leave the five optional endpoint fields blank unless your catalog is incomplete.

    Click **Connect**. CloudThinker requests a token from Keystone and shows a **Connected** status.
  </Step>
</Steps>

## Connection details

| Field | Description | Example |
| - | - | - |
| **OS\_AUTH\_URL** | Keystone v3 address; the path ends in `/v3` | `https://openstack.example.com:5000/v3` |
| **OS\_USERNAME** | Keystone user name | `cloudthinker` |
| **OS\_PASSWORD** | Password of that user | — |
| **OS\_PROJECT\_NAME** | Project every request is scoped to | `production` |
| **OS\_USER\_DOMAIN\_NAME** | Domain that contains the user. Defaults to `Default` | `Default` |
| **OS\_PROJECT\_DOMAIN\_NAME** | Domain that contains the project. Defaults to `Default` | `Default` |
| **OS\_REGION\_NAME** | Region in your service catalog. Defaults to `RegionOne` | `RegionOne` |
| **OS\_INTERFACE** | **Public endpoint** (default), **Internal endpoint**, or **Admin endpoint** | **Public endpoint** |
| **OS\_VERIFY\_SSL** | **Verify SSL certificate** (default) or **Skip SSL verification** | **Verify SSL certificate** |

Five optional fields let you bypass the Keystone catalog for one service: **OS\_IMAGE\_ENDPOINT\_OVERRIDE**, **OS\_COMPUTE\_ENDPOINT\_OVERRIDE**, **OS\_NETWORK\_ENDPOINT\_OVERRIDE**, **OS\_VOLUMEV3\_ENDPOINT\_OVERRIDE**, and **OS\_PLACEMENT\_ENDPOINT\_OVERRIDE**. Each takes a full `http(s)` URL.

<Warning>
  There is no field for a custom certificate authority. For a cloud with a self-signed certificate, **Skip SSL verification** is the only way to connect, and it removes protection against someone impersonating your cloud. Use it for lab clouds only. **Internal endpoint** works only if CloudThinker can reach your control-plane network.
</Warning>

## Required permissions

Keystone ships three default roles, `admin`, `member`, and `reader`. OpenStack documents `reader` as read-only access to resources within a project, and the roles are nested, so `member` includes `reader`.

* Start with `reader` on the project for inspection.
* Which role each service accepts depends on your cloud's policies. If a service refuses a request, grant the narrowest role that it accepts.
* Every request is scoped to the project. Questions across all projects usually need the `admin` role; without it OpenStack can answer `403 Forbidden`.

<Tip>
  OpenStack's documentation cautions that the `reader` role is the lowest level of authorization and that default policies may not expose sensitive information to it. Check what your cloud returns before you rely on it for audits.
</Tip>

## Agent capabilities

| Capability | Description |
| - | - |
| **Inventory** | List servers, volumes, networks, subnets, images, flavors, projects, and the service catalog |
| **Detail** | Inspect one server, volume, network, or image |
| **Idle and unused** | Find active servers worth right-sizing and unattached volumes |
| **Quotas** | Show quota use and flag projects above 80% |
| **Capacity** | Review flavors and, where your role allows, hypervisors |
| **Network drift** | Flag security group rules open to the whole internet |
| **Changes** | Stop, reboot, resize, or delete servers, volumes, images, and networks — each change **requires approval** |

See [Approval](/guide/approval) for how gated changes work.

### Verify the connection

```text theme={null}
Summarize my OpenStack project: servers, volumes, networks, images, and quota use
```

### Example prompts

```text theme={null}
Which volumes are unattached and older than 30 days?
Which security group rules allow traffic from 0.0.0.0/0?
Which quotas in my project are above 80% used?
```

## Troubleshooting

<Accordion title="Failed to connect to OpenStack">
  Keystone did not issue a token. Check the user name, password, project name, and domain names, that the address is reachable from CloudThinker, and that the user has a role on the project. A certificate CloudThinker does not trust also fails here unless **Skip SSL verification** is selected.
</Accordion>

<Accordion title="OS_AUTH_URL must be a Keystone v3 URL (http(s)://host[:port]/[path/]v3)">
  The address is not a Keystone v3 URL, or it contains credentials, a query string, or a fragment. Use the address from your openrc file, which ends in `/v3`.
</Accordion>

<Accordion title="OS_REGION_NAME must contain only letters, digits, '_', '-' (max 64 chars)">
  The region has a space or another character. Copy the region name exactly as it appears in your service catalog.
</Accordion>

<Accordion title="OS_IMAGE_ENDPOINT_OVERRIDE must be an http(s) URL with a host">
  An optional endpoint field holds something other than a full URL; the same message names whichever override field is wrong. Enter a URL such as `https://image.example.com`, or clear the field.
</Accordion>

<Accordion title="Invalid OpenStack connection configuration">
  The authentication address is empty. Enter your Keystone v3 address and connect again.
</Accordion>

<Accordion title="Connection 'openstack' already exists. Only one instance is allowed.">
  This workspace already has an OpenStack connection. Edit the existing one or disconnect it first.
</Accordion>

<Accordion title="403 Forbidden on a cross-project question">
  Questions across all projects usually need the `admin` role. Ask about your own project, or grant the user that role.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use an https address** — CloudThinker accepts an `http` Keystone address, but your password would then travel unencrypted.
- **Keep certificate checks on** — **Skip SSL verification** is for lab clouds with self-signed certificates.

## Related

<CardGroup cols={2}>
  <Card title="Kubernetes Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    Workload analysis, resource optimization, and cluster operations
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    How approval-gated actions work
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.