> ## 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 an OpenStack project so agents can inventory servers, volumes, networks, and quotas, flag waste and drift, and run approved changes Connect your OpenStack cloud to let CloudThinker agents inventory servers, volumes, networks, images, flavors, and quotas, flag waste and open security groups, and make changes through your Approvals. The connection signs in to Keystone (the OpenStack Identity service) with a **user name and password**, scoped to one project in one region. ## Prerequisites * A Keystone v3 address and catalog endpoints (Nova, Neutron, Cinder, Glance, Placement) with public hostnames that are reachable from the internet, because commands run in the CloudThinker cloud. Use `https`: `http` works but sends the password unencrypted. Behind a firewall, allow CloudThinker's egress IPs. These docs don't publish CloudThinker's egress IP list: ask your CloudThinker contact, or [contact us](https://cloudthinker.io/contact). If the catalog lists internal hostnames, see the endpoint overrides in [Connection details](#connection-details). * A Keystone user that signs in with a **password alone**. Application credentials and federated sign-in are not supported, and the user must not have multi-factor rules enforced in Keystone. * 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. * Cloud admin rights, or an admin who can create a user and assign it a role. > [!NOTE] > > A workspace holds one OpenStack connection, and it covers one project in one region. For more projects or regions, [create one workspace per project](https://docs.cloudthinker.io/guide/workspaces.md#create-a-workspace). Use a dedicated user with a long random password. ## Setup **1. Find your sign-in values** In the OpenStack dashboard (Horizon), open **Project → API Access** and click **Download OpenStack RC File** (Identity API v3). Or ask your cloud administrator. It lists the auth URL, project name, user name, domain names, and region, using the same `OS_*` names as the CloudThinker form. The RC file prompts for the password when you source it and doesn't store it. If you use `clouds.yaml`, the same values sit under `auth:`, and the region is `region_name`. **2. Create or choose a Keystone user** Use a dedicated user for CloudThinker and give it the `reader` role on the project. As a cloud admin, replace `` and `` with your values (`Default` is the domain on most clouds): ```bash theme={null} openstack user create --domain --password-prompt cloudthinker openstack role add --user cloudthinker --user-domain \ --project --project-domain reader ``` **Success state:** `openstack role assignment list --user cloudthinker --names` shows `reader` on your project. You can widen the role later if you want agents to make changes. **3. Check access from outside your network** The RC file from step 1 signs in as you. Copy it, change `OS_USERNAME` to `cloudthinker` (and `OS_USER_DOMAIN_NAME` if that user lives in another domain), then on a machine outside your network source the copy, enter the `cloudthinker` password at the prompt, and run: ```bash theme={null} source cloudthinker-openrc.sh openstack token issue openstack server list ``` **Success state:** `token issue` prints a token with an `expires` time, and `server list` prints your servers (or an empty table) without a timeout. CloudThinker runs the same `openstack token issue` to test the connection, so if it fails here, it fails in CloudThinker too. **4. Add the connection in CloudThinker** In the sidebar, click **More → Workspace settings → Connections**, then on the **Builtin Connections** tab select **OpenStack**, and fill in the fields from [Connection details](#connection-details). Leave the five endpoint override fields blank unless your service catalog is incomplete. Click **Connect**. **Success state:** the connection shows **Connecting** and **Verifying**, then a **Connected** status. CloudThinker requests a token from Keystone to prove the credentials work. ## Connection details | Field | Required | Description | Example | | - | - | - | - | | **OS\_AUTH\_URL** | Yes | Keystone v3 address. The path ends in `/v3` | `https://openstack.example.com:5000/v3` | | **OS\_USERNAME** | Yes | Keystone user name | `cloudthinker` | | **OS\_PASSWORD** | Yes | Password of that user | `********` | | **OS\_PROJECT\_NAME** | Yes | Project every request is scoped to | `production` | | **OS\_USER\_DOMAIN\_NAME** | Yes, prefilled | Domain that holds the user. Defaults to `Default` | `Default` | | **OS\_PROJECT\_DOMAIN\_NAME** | Yes, prefilled | Domain that holds the project. Defaults to `Default` | `Default` | | **OS\_REGION\_NAME** | Yes, prefilled | Region in your service catalog. Letters, digits, `_`, and `-`, up to 64 characters. Defaults to `RegionOne` | `RegionOne` | | **OS\_INTERFACE** | Yes, prefilled | **Public endpoint** (default), **Internal endpoint**, or **Admin endpoint**. Keep **Public endpoint**. Pick **Internal endpoint** or **Admin endpoint** only if those catalog URLs are reachable from the internet through your allowlist; otherwise the connection times out | **Public endpoint** | | **OS\_VERIFY\_SSL** | Yes, prefilled | **Verify SSL certificate** (default) or **Skip SSL verification** | **Verify SSL certificate** | Five optional fields bypass the Keystone catalog for one service each: **OS\_IMAGE\_ENDPOINT\_OVERRIDE** (Glance), **OS\_COMPUTE\_ENDPOINT\_OVERRIDE** (Nova), **OS\_NETWORK\_ENDPOINT\_OVERRIDE** (Neutron), **OS\_VOLUMEV3\_ENDPOINT\_OVERRIDE** (Cinder), and **OS\_PLACEMENT\_ENDPOINT\_OVERRIDE** (Placement). Each takes a full `http` or `https` URL. To check whether you need them, run `openstack catalog list` and confirm that every `public` URL resolves from outside your network. Set an override only for a service whose URL doesn't. > [!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. ## Required permissions Keystone ships three default roles: `admin`, `member`, and `reader`. OpenStack describes `reader` as read-only access within a project, and `member` includes `reader`. | You want agents to | Role on the project | | - | - | | Inventory and audit the project | `reader` | | Stop, reboot, resize, or delete resources | A custom role your cloud's policy files allow for each action (recommended), or `member`. See the table below | | Answer questions across all projects | Not supported: keep to one project per workspace. Cross-project calls usually need `admin`, which this connection shouldn't have (see the warning below) | `member` also lets agents create servers, networks, and volumes, which goes past the changes agents make. For least privilege, create a custom role and allow only these policies: | Approved change | Policy | | - | - | | Stop, reboot, resize, delete a server (Nova) | `os_compute_api:servers:stop`, `os_compute_api:servers:reboot`, `os_compute_api:servers:resize`, `os_compute_api:servers:delete` | | Delete a volume (Cinder) | `volume:delete` | | Delete an image (Glance) | `delete_image` | | Delete a network (Neutron) | `delete_network` | Your cloud operator wires the role into each service's policy file (Nova, Cinder, Glance, Neutron) and deploys it there. A Nova entry looks like this: ```yaml theme={null} "os_compute_api:servers:stop": "role:cloudthinker-ops" ``` See the [Nova policy reference](https://docs.openstack.org/nova/latest/configuration/policy.html). Either way, agents can delete only resources the project owns, not shared or public images or shared networks. > [!WARNING] > > In most deployments the default `admin` role is effectively cloud-wide, even when you assign it on one project. Don't give it to this connection. Keep cross-project questions to a person with admin access. > [!TIP] > > Start with `reader`. Default policies keep some admin-only details from it, such as hypervisors and the host a server runs on. Check what your cloud returns before you rely on it for an audit. ## Agent capabilities | Capability | What agents can do | | - | - | | **Inventory** | List servers, volumes, networks, subnets, images, flavors, projects, and the service catalog, and inspect one in detail. Listing every project usually needs `admin` | | **Idle and unused** | Flag right-sizing candidates from flavor size, power state, and launch time, and find volumes that are unattached and were created more than 30 days ago (from the volume's `created_at`). CPU metrics are used only if your cloud runs Telemetry (Ceilometer or Gnocchi). Without it, candidates come from flavor, power state, and launch time alone | | **Quotas** | Show quota use for instances, cores, RAM, volumes, gigabytes, and networks, and flag anything above 80% | | **Capacity** | Review flavors and, with `admin` under default policies, hypervisors | | **Network drift** | Flag security group rules open to `0.0.0.0/0` | | **Approved changes** | Stop, reboot, resize, or delete servers, and delete volumes, images, or networks | The 30-day and 80% thresholds are defaults. Name a different number in your question, such as `volumes unattached and older than 90 days`. Reads run without asking. Every change goes through [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself. ### Verify the connection ```text theme={null} Summarize my OpenStack project: servers, volumes, networks, images, and quota use ``` Expect counts for each resource type and quota use for the project, with any quota above 80% called out. ### Example prompts ```text theme={null} Which volumes are unattached, and how large is each one? Which security group rules allow traffic from 0.0.0.0/0? Which quotas in my project are above 80% used? ``` ## Troubleshooting > [accordion] Failed to connect to OpenStack > > Keystone did not issue a token. The message doesn't say why, so run `openstack token issue` with the same values from outside your network, as in [step 3](#setup), and read its error: > > * `401` or `The request you have made requires authentication`: check the user name, password, project name, both domain names, and that the user has a role on the project. > * A timeout or `Unable to establish connection`: the address isn't reachable from the internet. > * An SSL or certificate error: the certificate isn't trusted. Select **Skip SSL verification** for a lab cloud only. > [accordion] OS\_AUTH\_URL must be a Keystone v3 URL > > The address doesn't end in `/v3`, or it contains credentials, a query string, or a fragment. Copy `OS_AUTH_URL` from your openrc file. > [accordion] 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] An endpoint override must be an http(s) URL with a host > > An optional override field holds something other than a full URL. The message names the field. Enter a URL such as `https://image.example.com`, or clear the field. > [accordion] Invalid OpenStack connection configuration > > **OS\_AUTH\_URL** is empty. Enter your Keystone v3 address and connect again. > [accordion] Connection 'openstack' already exists. Only one instance is allowed. > > This workspace already has an OpenStack connection. Edit that connection, or disconnect it first. > [accordion] 403 Forbidden on a question across projects > > Cross-project questions usually need the `admin` role. Ask about your own project instead. See the warning in [Required permissions](#required-permissions) before you grant `admin`. ## 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 then travels unencrypted. - **Keep certificate checks on**: reserve **Skip SSL verification** for lab clouds with self-signed certificates. - **Revoke at the source**: disable the Keystone user, or remove its role assignment on the project. - **Plan for password changes**: a new password breaks the connection until you enter it in CloudThinker. A workspace holds one OpenStack connection, so there's no in-place swap while it's healthy: once the connection shows **Error**, enter the new password with **Replace credentials**. To change it before then, disconnect and connect again, which reruns Discovery, puts **Allow writes** back to on, and means checking that Rules still name the connection. See [Rotate a credential](https://docs.cloudthinker.io/guide/connections/overview.md#rotate-a-credential). If your Keystone enforces password expiry, exempt this user. ## Related > [card] [Connections](https://docs.cloudthinker.io/guide/connections/overview.md) > > See every service you can connect and how connection status works. > [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) > > Decide which OpenStack changes run, wait for a person, or are refused. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.