How-to Guides

Task-oriented recipes for deploying, operating, upgrading and troubleshooting OpenStack. Commands target the 2026.1 Gazpacho series and a current python-openstackclient. Background is in Explanation; defaults, ports and version matrices are in Reference.

Deployment

DevStack (Development)

DevStack builds a single-node development cloud from source. Never use it for production. Run it on a disposable VM as a non-root user with sudo:

sudo useradd -s /bin/bash -d /opt/stack -m stack
sudo chmod +x /opt/stack
echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
sudo -u stack -i

git clone https://opendev.org/openstack/devstack
cd devstack
cat > local.conf <<'EOF'
[[local|localrc]]
ADMIN_PASSWORD=secret
DATABASE_PASSWORD=$ADMIN_PASSWORD
RABBIT_PASSWORD=$ADMIN_PASSWORD
SERVICE_PASSWORD=$ADMIN_PASSWORD
EOF
./stack.sh

Passwords

DevStack docs warn to use only alphanumeric characters in these passwords, as some services fail with special characters.

Production (Kolla-Ansible)

Kolla-Ansible deploys the Kolla container images with Ansible. The steps below follow the 2026.1 quickstart (all-in-one inventory; swap in multinode for real clusters). Supported hosts for 2026.1: Ubuntu 24.04, Debian 13, Rocky Linux 10, CentOS Stream 10.

# 1. Virtualenv with kolla-ansible from the matching stable branch
python3 -m venv ~/kolla-venv
source ~/kolla-venv/bin/activate
pip install -U pip
pip install git+https://opendev.org/openstack/kolla-ansible@stable/2026.1

# 2. Config directory, example globals/passwords and inventory
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
cp -r ~/kolla-venv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
cp ~/kolla-venv/share/kolla-ansible/ansible/inventory/all-in-one .

# 3. Ansible Galaxy dependencies and generated passwords
kolla-ansible install-deps
kolla-genpwd

# 4. Edit /etc/kolla/globals.yml (kolla_base_distro, network_interface,
#    neutron_external_interface, kolla_internal_vip_address), then:
kolla-ansible bootstrap-servers -i ./all-in-one
kolla-ansible prechecks -i ./all-in-one
kolla-ansible deploy -i ./all-in-one

# 5. Client and admin credentials
pip install python-openstackclient -c https://releases.openstack.org/constraints/upper/2026.1
kolla-ansible post-deploy -i ./all-in-one   # writes /etc/kolla/clouds.yaml

Command syntax

Current Kolla-Ansible uses kolla-ansible <action> -i <inventory>. Older guides that put -i before the action, or use pip install kolla-ansible without a branch, target older releases.

Production on Kubernetes (OpenStack-Helm)

OpenStack-Helm publishes charts on tarballs.opendev.org and a Helm plugin (helm osh) that assembles per-release value overrides. After preparing Kubernetes (1.33 to 1.35 per the README), Ceph or another storage class, and ingress:

helm repo add openstack-helm https://tarballs.opendev.org/openstack/openstack-helm
helm plugin install https://opendev.org/openstack/openstack-helm-plugin

export OPENSTACK_RELEASE=2025.1
export FEATURES="${OPENSTACK_RELEASE} ubuntu_noble"
export OVERRIDES_DIR=$(pwd)/overrides

helm upgrade --install keystone openstack-helm/keystone \
    --namespace=openstack \
    $(helm osh get-values-overrides -p ${OVERRIDES_DIR} -c keystone ${FEATURES})
helm osh wait-for-pods openstack

Repeat for the other charts (RabbitMQ, MariaDB, Memcached, Glance, Placement, Nova, Neutron, Cinder, Horizon) in the order given by the upstream install guide. The upstream example still uses OPENSTACK_RELEASE=2025.1; the README lists 2025.2 and 2026.1 as tested too. Rackspace's Genestack wraps these same charts with Kustomize if you want an opinionated distribution.

Upgrades

Upgrade with Kolla-Ansible (adjacent or SLURP skip-level)

Upgrades go from one release to the next, or from a SLURP to the next SLURP (for example 2025.1 Epoxy to 2026.1 Gazpacho). Read the release notes of every project for both the target and any skipped release first.

source ~/kolla-venv/bin/activate
pip install --upgrade git+https://opendev.org/openstack/kolla-ansible@stable/2026.1
kolla-ansible install-deps

# Merge old passwords with any new ones
cp /etc/kolla/passwords.yml passwords.yml.old
cp ~/kolla-venv/share/kolla-ansible/etc/kolla/passwords.yml passwords.yml.new
kolla-genpwd -p passwords.yml.new
kolla-mergepwd --old passwords.yml.old --new passwords.yml.new --final /etc/kolla/passwords.yml

kolla-ansible pull -i ./multinode
kolla-ansible prechecks -i ./multinode
kolla-ansible upgrade -i ./multinode

SLURP extra step

For a skip-level upgrade, first upgrade ansible-core to the range the target release supports, and upgrade RabbitMQ to the intermediate version described in the Kolla-Ansible RabbitMQ SLURP guide, because RabbitMQ cannot jump two major versions at once.

Plan the Upgrade Window

1. Check the target is supported from your release in the SLURP matrix.
2. Move off removed features first (for example the Neutron Linux bridge driver was removed in 2025.1; Kolla-Ansible no longer deploys Swift since 2025.1).
3. Back up every database (mariadb-dump or Kolla's kolla-ansible mariadb-backup) and Fernet keys.
4. Upgrade a staging cloud with the same inventory and run Tempest or Rally smoke tests.
5. Upgrade production control plane, then compute hosts; watch openstack compute service list for down services.

Authentication

# clouds.yaml (preferred) or an openrc file
export OS_CLOUD=mycloud
# source admin-openrc.sh

# Verify authentication and catalog
openstack token issue
openstack catalog list
openstack endpoint list

Compute (Nova)

openstack server list --long

openstack server create myvm \
  --image ubuntu-24.04 \
  --flavor m1.large \
  --network private-net \
  --key-name mykey \
  --security-group default \
  --availability-zone az1

# Live migrate (let the scheduler pick, or name a host)
openstack server migrate --live-migration myvm
openstack server migrate --live-migration --host compute-02 myvm
openstack server migration list --server myvm

# Resize and confirm
openstack server resize --flavor m1.xlarge myvm
openstack server resize confirm myvm

# Console access
openstack console url show myvm
openstack console log show --lines 50 myvm

Removed flag

The old openstack server migrate --live <host> form is gone from current OSC; use --live-migration plus --host.

Networking (Neutron)

# Network + subnet
openstack network create private-net
openstack subnet create private-sub \
  --network private-net \
  --subnet-range 10.0.0.0/24 \
  --gateway 10.0.0.1 \
  --dns-nameserver 9.9.9.9

# Router + external gateway
openstack router create main-router
openstack router set main-router --external-gateway public-net
openstack router add subnet main-router private-sub

# Floating IP
openstack floating ip create public-net
openstack server add floating ip myvm 203.0.113.10

Open a Port with a Security Group Rule

The positional argument is the security group; add rules to a dedicated group rather than widening default.

openstack security group create web
openstack security group rule create web \
  --protocol tcp --dst-port 443 --remote-ip 0.0.0.0/0
openstack security group rule create web \
  --protocol tcp --dst-port 22 --remote-ip 198.51.100.0/24
openstack server add security group myvm web

Storage (Cinder)

openstack volume create --size 100 --type ssd data-vol
openstack server add volume myvm data-vol

openstack volume snapshot create --volume data-vol snap-01
openstack volume backup create --name backup-01 data-vol

Images (Glance)

openstack image create ubuntu-24.04 \
  --file noble-server-cloudimg-amd64.img \
  --disk-format qcow2 --container-format bare \
  --public

openstack image list --long

Ceph backends

With Ceph RBD for Glance and Nova, upload images as raw so Nova can make copy-on-write clones; a qcow2 image forces a full download and conversion on every boot.

Orchestration (Heat)

# stack.yaml
heat_template_version: 2021-04-16
parameters:
  image:
    type: string
    default: ubuntu-24.04
resources:
  server:
    type: OS::Nova::Server
    properties:
      image: { get_param: image }
      flavor: m1.large
      networks:
        - network: private-net

openstack stack create mystack -t stack.yaml
openstack stack list
openstack stack delete mystack

Security Tasks

Rotate Fernet Keys

Keystone encrypts tokens with a rotating set of Fernet keys. Rotate on every Keystone node from the same key repository (Kolla-Ansible automates this with a cron container):

keystone-manage fernet_rotate --keystone-user keystone --keystone-group keystone
# then distribute /etc/keystone/fernet-keys/ to all Keystone nodes

Keep max_active_keys large enough that keys outlive the token expiration (default 3600 s).

Enable TLS in Kolla-Ansible

In /etc/kolla/globals.yml set kolla_enable_tls_external: "yes" and kolla_enable_tls_internal: "yes" with certificates, and rabbitmq_enable_tls: "yes" for AMQP over TLS (port 5671), then run kolla-ansible reconfigure -i ./multinode.

Performance Tuning

Allocation ratios are set per compute host in nova.conf (or per resource provider in Placement). Since Stein the initial defaults are initial_cpu_allocation_ratio = 4.0 and initial_ram_allocation_ratio = 1.0.

[DEFAULT]
# Explicit values override the initial_* defaults and Placement edits
cpu_allocation_ratio = 4.0
ram_allocation_ratio = 1.0
max_concurrent_live_migrations = 2

[libvirt]
# 2026.1+: parallel memory transfer; each connection can use a CPU core
live_migration_parallel_connections = 4

Component	Parameter	Recommendation
Nova	cpu_allocation_ratio	4.0 is the initial default; lower for CPU-bound workloads, use cpu_dedicated_set for pinning
Nova	ram_allocation_ratio	1.0 (default) unless you run memory ballooning deliberately
Nova	max_concurrent_live_migrations	Default 1; 2 to 4 on a dedicated migration network
Neutron (ML2/OVS)	l3_ha	Enable for router HA (OVN routers are HA by design)
Cinder	rbd_pool	Dedicated Ceph pool per volume type or tier

Common Issues

Issue	Diagnosis	Fix
Service down	openstack compute service list, openstack network agent list	Check service logs, restart the container or unit
VM stuck in BUILD or ERROR	openstack server show <id> (fault field)	Check nova-conductor and nova-scheduler logs, Placement capacity, quotas
"No valid host was found"	openstack allocation candidate list --resource VCPU=2 (osc-placement plugin)	Free capacity, fix allocation ratios, check traits and AZs
Network unreachable	openstack port show <id>	Check security groups, port binding (binding_vif_type), OVN chassis registration
RabbitMQ cluster issues	rabbitmqctl cluster_status	Recover the partitioned node, then restart dependent services
Galera cluster down	kolla-ansible mariadb-recovery -i ./multinode	Recovers from the most advanced node

Troubleshooting

# Service and agent health
openstack compute service list
openstack network agent list
openstack volume service list

# Hypervisor capacity (OSC marks 'hypervisor stats show' deprecated; Nova
# removed the statistics API from compute microversion 2.88 onward)
openstack hypervisor list --long
openstack resource provider list          # osc-placement plugin

# Quota check (project is positional)
openstack quota show myproject

Sources

• DevStack quick start
• Kolla-Ansible quickstart
• Kolla-Ansible operating and upgrade guide
• OpenStack-Helm installation
• OpenStackClient command reference
• Nova configuration options
• Keystone Fernet token FAQ