▤ Stackers Network

Learn OpenStack · deploy/config-build

Getting Started — First Steps

Before building any configuration, do these steps first. Always.

1. Read the Release Notes

Before anything else, read the release notes for the target release: https://docs.openstack.org/releasenotes/kolla-ansible/

This catches breaking changes, deprecated options, and known issues before you hit them.

2. Get the STOCK globals.yml and Inventory

Never write globals.yml from scratch. Copy the full template from kolla-ansible. It has every option with documentation comments, and hidden defaults you need to know about (like kolla_base_distro_version).

source /opt/kolla-venv/bin/activate

# Stock files are under share/, NOT the Python package path
KOLLA_SHARE="/opt/kolla-venv/share/kolla-ansible"

# Copy the full globals.yml template
cp "$KOLLA_SHARE/etc_examples/kolla/globals.yml" globals.yml

# Copy the stock inventory (all-in-one or multinode)
mkdir -p inventory
cp "$KOLLA_SHARE/ansible/inventory/all-in-one" inventory/hosts
# or: cp "$KOLLA_SHARE/ansible/inventory/multinode" inventory/hosts

Important: The stock files live at /opt/kolla-venv/share/kolla-ansible/, NOT at the path returned by kolla_ansible.__file__. The Python path points to the package code, not the etc_examples.

Why use the stock files? git diff will show exactly what was customized. A from-scratch file hides which defaults are relied on and makes it easy to miss important settings. The stock file also has inline documentation for every option.

Commit the originals first:

git add globals.yml inventory/
git commit -m "stock kolla-ansible globals.yml and inventory"

Then edit and commit your changes separately — the diff shows exactly what you customized.

If kolla-ansible isn't installed yet, download directly:

curl -sL https://opendev.org/openstack/kolla-ansible/raw/branch/stable/2025.1/etc/kolla/globals.yml > globals.yml
curl -sL https://opendev.org/openstack/kolla-ansible/raw/branch/stable/2025.1/ansible/inventory/all-in-one > inventory/hosts

3. Verify Host Interfaces

Always verify actual interface names on the target hosts before editing globals.yml. Operators often get interface names wrong.

ssh root@<host> ip -br addr

Look for: - Management interface: the one with an IP on the management network - External interface: the one for provider/external networks (should be UP but no IP)

4. Generate passwords.yml

kolla-genpwd requires the passwords template file to exist first:

source /opt/kolla-venv/bin/activate
KOLLA_SHARE="/opt/kolla-venv/share/kolla-ansible"

# kolla-genpwd REQUIRES the template file to exist first — it will fail without it
cp "$KOLLA_SHARE/etc_examples/kolla/passwords.yml" passwords.yml

# Generate random passwords (fills in the template)
kolla-genpwd -p passwords.yml

kolla-genpwd will fail if the file doesn't exist. You must seed it from the template first.

Copy back to local repo immediately. If passwords are generated on the host, scp them back:

scp root@<host>:/etc/kolla/passwords.yml ./passwords.yml

Without this, losing the host means losing all credentials.

Encrypt at rest — passwords.yml contains plaintext credentials for every service:

# Option 1: SOPS
sops --encrypt --in-place passwords.yml

# Option 2: Ansible Vault
ansible-vault encrypt passwords.yml

# Option 3: .gitignore (minimum)
echo "passwords.yml" >> .gitignore

5. Apply Known Issue Workarounds

Before editing globals.yml, check deploy/deploy/known-issues-2025.1.md for required workarounds. For 2025.1, you MUST set:

enable_proxysql: "no"
keystone_wsgi_provider: "apache"
kolla_install_type: "binary"

6. AIO Self-SSH Setup

For all-in-one deployments, the host must be able to SSH to itself (kolla-ansible uses SSH even for AIO):

ssh-keygen -t rsa -N '' -f ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
ssh -o StrictHostKeyChecking=no root@<host-ip> 'echo ok'

7. Copy Config to /etc/kolla

Before any kolla-ansible command, config must be in /etc/kolla/:

sudo mkdir -p /etc/kolla
sudo cp globals.yml /etc/kolla/globals.yml
sudo cp passwords.yml /etc/kolla/passwords.yml
# If you have service overrides:
sudo cp -r config/ /etc/kolla/config/

Order of Operations

  1. Read release notes
  2. Install kolla-ansible in a venv
  3. Copy stock globals.yml and inventory/hosts from kolla-ansible
  4. Commit stock files
  5. Verify host interface names
  6. Edit globals.yml — uncomment and modify only what you need
  7. Edit inventory/hosts — set host assignments at the top
  8. Apply known issue workarounds to globals.yml
  9. Generate passwords.yml
  10. Copy everything to /etc/kolla/
  11. Run kolla-ansible bootstrap-servers
  12. Run kolla-ansible prechecks
  13. Run kolla-ansible pull
  14. Run kolla-ansible deploy
  15. Run kolla-ansible post-deploy
  16. Copy passwords.yml back to local repo + encrypt