openstack-kolla-ansible

OpenStack Kolla-Ansible -- Deployment Engine

Introduction

Kolla-Ansible is the production-grade deployment engine for containerized OpenStack. It uses Ansible playbooks to deploy, configure, and manage Docker containers for each OpenStack service. Every core service -- Keystone, Nova, Neutron, Cinder, Glance, Swift, Heat, Horizon -- plus supporting infrastructure (MariaDB, RabbitMQ, Memcached, HAProxy) runs in its own Docker container, managed through a single unified tool.

The Kolla project has two components: Kolla builds the Docker images for each OpenStack service. Kolla-Ansible deploys those images to target hosts using Ansible. In practice, most operators use pre-built images from the Kolla registry and only interact with Kolla-Ansible for deployment and lifecycle management.

Kolla-Ansible supports CentOS Stream 9, Rocky Linux 9, and Ubuntu 22.04 as host operating systems. Container images are available in two variants: source (built from OpenStack source code) and binary (built from distribution packages). For production stability, binary images pinned to a specific OpenStack release are recommended.

The deployment lifecycle follows four primary operations: bootstrap (prepare the host environment), deploy (install and start all services), reconfigure (change configuration on a running deployment), and upgrade (move to a new OpenStack release). Each operation is idempotent -- running it again produces the same result.

Bootstrap

Bootstrap prepares the host environment for OpenStack deployment. This is a one-time operation per host.

Prerequisites

# System requirements
# - CentOS Stream 9 (recommended), Rocky Linux 9, or Ubuntu 22.04
# - Minimum 16 GB RAM, 100 GB disk, 2 network interfaces
# - Python 3.9+
# - Docker CE or Podman (Kolla-Ansible installs Docker if missing)

# Verify Python version
python3 --version

# Verify network interfaces
ip link show
# You need at least 2 interfaces: one for management (API traffic)
# and one for Neutron external (tenant/provider network traffic)

Install Kolla-Ansible

# Create a Python virtual environment (recommended)
python3 -m venv /opt/kolla-venv
source /opt/kolla-venv/bin/activate

# Install kolla-ansible (pin to a specific OpenStack release)
pip install 'kolla-ansible==17.0.*'    # For 2024.1 (Caracal)
# Or for the latest stable:
pip install kolla-ansible

# Install Ansible dependencies
kolla-ansible install-deps

Generate Configuration

# Copy default configuration files
cp -r /opt/kolla-venv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla/

# This creates:
# /etc/kolla/globals.yml    - Main configuration file
# /etc/kolla/passwords.yml  - Service passwords (empty, needs generation)

# Generate random passwords for all services
kolla-genpwd

# IMPORTANT: Back up passwords.yml immediately after generation
cp /etc/kolla/passwords.yml /etc/kolla/passwords.yml.backup

Configure globals.yml

This is the central configuration file. Every deployment decision is encoded here:

# /etc/kolla/globals.yml

# Base configuration
kolla_base_distro: "centos"
kolla_install_type: "binary"
openstack_release: "2024.1"

# Networking
kolla_internal_vip_address: "10.0.0.100"    # VIP for internal API traffic
network_interface: "eth0"                     # Management network interface
neutron_external_interface: "eth1"            # Neutron external bridge interface

# Optional: External VIP for public API access
# kolla_external_vip_address: "192.168.1.100"
# kolla_enable_tls_external: "yes"

# Docker configuration
# docker_registry: "quay.io"                 # Custom registry if needed
# docker_namespace: "openstack.kolla"

# Service enablement (enable what you need)
enable_keystone: "yes"      # Identity (always required)
enable_nova: "yes"          # Compute
enable_neutron: "yes"       # Networking
enable_cinder: "yes"        # Block storage
enable_glance: "yes"        # Image service
enable_horizon: "yes"       # Web dashboard
enable_heat: "yes"          # Orchestration
enable_swift: "yes"         # Object storage

# Optional services
# enable_ceilometer: "yes"  # Telemetry
# enable_aodh: "yes"        # Alarming
# enable_magnum: "yes"      # Container orchestration

# Storage backend
# cinder_backend_lvm: "yes"                  # LVM for Cinder (default)
# cinder_volume_group: "cinder-volumes"

# Neutron networking
neutron_plugin_agent: "openvswitch"           # OVS or OVN
# neutron_plugin_agent: "ovn"                 # For OVN backend

Configure Inventory

# For single-node (all-in-one) deployment
cp /opt/kolla-venv/share/kolla-ansible/ansible/inventory/all-in-one /etc/kolla/

# For multi-node deployment
cp /opt/kolla-venv/share/kolla-ansible/ansible/inventory/multinode /etc/kolla/
# Then edit /etc/kolla/multinode to assign hosts to groups:
# [control], [network], [compute], [storage], [monitoring]

Bootstrap Servers

# Bootstrap the host(s) - installs Docker, configures system
kolla-ansible -i /etc/kolla/all-in-one bootstrap-servers

# This performs:
# - Installs Docker CE and configures the Docker daemon
# - Configures kernel modules (br_netfilter, overlay)
# - Sets sysctl parameters (net.bridge.bridge-nf-call-iptables)
# - Creates kolla user and directory structure
# - Pulls base container images

Pre-Deployment Checks

# Run pre-deployment validation
kolla-ansible -i /etc/kolla/all-in-one prechecks

# Prechecks verify:
# - Network interfaces exist and are configured
# - Required ports are not in use (5000, 8774, 9696, etc.)
# - Docker is running and functional
# - Required packages are installed
# - Disk space is sufficient
# - Firewall rules allow required traffic

If prechecks fail, address each reported issue before proceeding to deploy. Common fixes are documented in the Troubleshoot section.

Deploy

Deploy installs and starts all enabled OpenStack services.

Execute Deployment

# Deploy all enabled services
kolla-ansible -i /etc/kolla/all-in-one deploy

# Deployment proceeds in phases:
# 1. Infrastructure (MariaDB, RabbitMQ, Memcached, HAProxy)
# 2. Identity (Keystone)
# 3. Image (Glance)
# 4. Compute (Nova)
# 5. Network (Neutron)
# 6. Block Storage (Cinder)
# 7. Object Storage (Swift)
# 8. Orchestration (Heat)
# 9. Dashboard (Horizon)
# 10. Monitoring/Telemetry (if enabled)

# Duration: 15-45 minutes depending on hardware and number of services

Post-Deploy

# Generate admin credentials and register endpoints
kolla-ansible -i /etc/kolla/all-in-one post-deploy

# This creates:
# /etc/kolla/admin-openrc.sh  - Admin credentials for CLI

Verify Deployment

# Source admin credentials
source /etc/kolla/admin-openrc.sh

# Verify all services are registered
openstack service list

# Verify each service endpoint
openstack endpoint list

# Verify compute is available
openstack hypervisor list

# Verify networking
openstack network agent list

# Verify images service
openstack image list

# Verify block storage
openstack volume service list

# Verify orchestration
openstack orchestration service list

# Quick health check -- all services should respond
openstack token issue         # Keystone
openstack flavor list         # Nova
openstack network list        # Neutron
openstack volume type list    # Cinder
openstack image list          # Glance
openstack stack list          # Heat

Initialize Demo Resources

# Run the init-runonce script to create demo networks, images, and flavors
# This script ships with Kolla-Ansible
/opt/kolla-venv/share/kolla-ansible/init-runonce

# It creates:
# - External network (public) and internal network (demo-net)
# - A router connecting internal to external
# - Cirros test image
# - Basic flavors (m1.tiny through m1.xlarge)
# - Security group rules for SSH and ICMP

# Test with an instance launch
openstack server create --image cirros --flavor m1.tiny \
  --network