# openstack/kolla-ansible architecture

> Architecture diagram of the GitHub repository openstack/kolla-ansible, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openstack/kolla-ansible
- Repository: https://github.com/openstack/kolla-ansible

## Overview

Kolla Ansible is an Ansible-based deployment and operations tool for containerized OpenStack services and infrastructure. Operators invoke CLI commands such as deploy, upgrade, and reconfigure; the command layer selects playbooks, and the Ansible runner assembles configuration and launches Ansible. Ansible’s container module manages container lifecycle through Docker or Podman workers, with systemd integration. The README documents broad OpenStack and infrastructure coverage, but their playbooks are not in this tree. The graph includes indexed runtime modules and password utilities; unsampled deployment wiring is omitted.

Main entry points: [`kolla_ansible/cli/commands.py`](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cli/commands.py) (Operations commands), [`ansible/library/kolla_container.py`](https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_container.py) (Container module), [`ansible/module_utils/kolla_container_worker.py`](https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_container_worker.py) (Container worker), [`kolla_ansible/ansible.py`](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/ansible.py) (Ansible runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and orchestration"]
  node_commands["Operations commands<br/>[commands.py]"]
  node_runner["Ansible runner<br/>[ansible.py]"]
end

subgraph group_containers["Container runtime"]
  node_container_module["Container module<br/>[kolla_container.py]"]
  node_container_worker["Container worker"]
  node_docker_worker["Docker worker"]
  node_podman_worker["Podman worker"]
  node_systemd_worker["Systemd worker"]
  node_container_facts["Container facts"]
  node_toolbox["Kolla toolbox<br/>[kolla_toolbox.py]"]
end

subgraph group_filters["Ansible filters"]
  node_service_filters["Service filters<br/>[filters.py]"]
  node_filter_plugin["Service filter plugin<br/>[services.py]"]
  node_address["Address filters<br/>[kolla_address.py]"]
  node_address_plugin["Address filter plugin<br/>[address.py]"]
  node_url["URL formatting<br/>[kolla_url.py]"]
  node_address_context["Address context"]
  node_database_shards["Database shards<br/>[database_shards.py]"]
  node_database_plugin["Database filter plugin<br/>[database.py]"]
  node_nova_filters["Nova filters<br/>[nova_filters.py]"]
  node_fluentd_filters["Fluentd filters<br/>[fluentd_filters.py]"]
end

subgraph group_secrets["Password utilities"]
  node_password_ops["Password commands<br/>[genpwd.py]"]
  node_vault["Vault utilities<br/>[hashi_vault.py]"]
  node_read_password["Read passwords<br/>[readpwd.py]"]
  node_write_password["Write passwords<br/>[writepwd.py]"]
  node_merge_password["Merge passwords<br/>[mergepwd.py]"]
end

subgraph group_operations["Deployed cloud"]
  node_cloud_services["Cloud services"]
  node_infra_services["Infrastructure services"]
end

node_operator(("Operator"))
node_ansible["Ansible"]

node_operator -->|"invokes"| node_commands
node_commands -->|"runs playbooks"| node_runner
node_runner -->|"launches"| node_ansible
node_ansible -.->|"dispatches module"| node_container_module
node_container_module -->|"uses worker"| node_container_worker
node_container_module -->|"uses backend"| node_docker_worker
node_container_module -->|"uses backend"| node_podman_worker
node_container_worker -->|"uses systemd"| node_systemd_worker
node_docker_worker -->|"extends worker"| node_container_worker
node_podman_worker -->|"extends worker"| node_container_worker
node_commands -.->|"deploys"| node_cloud_services
node_commands -.->|"deploys"| node_infra_services
node_filter_plugin -->|"exposes"| node_service_filters
node_address_plugin -->|"exposes"| node_address
node_address -->|"formats URLs"| node_url
node_url -->|"formats context"| node_address_context
node_database_plugin -->|"exposes"| node_database_shards
node_read_password -->|"reads vault"| node_vault
node_write_password -->|"writes vault"| node_vault
node_operator -->|"generates secrets"| node_password_ops
node_operator -->|"reads secrets"| node_read_password
node_operator -->|"writes secrets"| node_write_password
node_operator -->|"merges secrets"| node_merge_password

click node_commands "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cli/commands.py"
click node_runner "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/ansible.py"
click node_container_module "https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_container.py"
click node_container_worker "https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_container_worker.py"
click node_docker_worker "https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_docker_worker.py"
click node_podman_worker "https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_podman_worker.py"
click node_systemd_worker "https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_systemd_worker.py"
click node_container_facts "https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_container_facts.py"
click node_toolbox "https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_toolbox.py"
click node_service_filters "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/filters.py"
click node_filter_plugin "https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/services.py"
click node_address "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/kolla_address.py"
click node_address_plugin "https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/address.py"
click node_url "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/kolla_url.py"
click node_address_context "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/put_address_in_context.py"
click node_database_shards "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/database_shards.py"
click node_database_plugin "https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/database.py"
click node_nova_filters "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/nova_filters.py"
click node_fluentd_filters "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/fluentd_filters.py"
click node_password_ops "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/genpwd.py"
click node_vault "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/hashi_vault.py"
click node_read_password "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/readpwd.py"
click node_write_password "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/writepwd.py"
click node_merge_password "https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/mergepwd.py"
click node_cloud_services "https://github.com/openstack/kolla-ansible/tree/master/ansible"
click node_infra_services "https://github.com/openstack/kolla-ansible/tree/master/ansible"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commands,node_runner toneBlue
class node_container_module,node_container_worker,node_docker_worker,node_podman_worker,node_systemd_worker,node_container_facts,node_toolbox toneAmber
class node_service_filters,node_filter_plugin,node_address,node_address_plugin,node_url,node_address_context,node_database_shards,node_database_plugin,node_nova_filters,node_fluentd_filters toneMint
class node_password_ops,node_vault,node_read_password,node_write_password,node_merge_password toneRose
class node_cloud_services,node_infra_services,node_operator,node_ansible toneIndigo
```

## Components

### CLI and orchestration

- [Operations commands](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cli/commands.py): `kolla_ansible/cli/commands.py`
- [Ansible runner](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/ansible.py): `kolla_ansible/ansible.py`

### Container runtime

- [Container module](https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_container.py): `ansible/library/kolla_container.py`
- [Container worker](https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_container_worker.py): `ansible/module_utils/kolla_container_worker.py`
- [Docker worker](https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_docker_worker.py): `ansible/module_utils/kolla_docker_worker.py`
- [Podman worker](https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_podman_worker.py): `ansible/module_utils/kolla_podman_worker.py`
- [Systemd worker](https://github.com/openstack/kolla-ansible/blob/master/ansible/module_utils/kolla_systemd_worker.py): `ansible/module_utils/kolla_systemd_worker.py`
- [Container facts](https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_container_facts.py): `ansible/library/kolla_container_facts.py`
- [Kolla toolbox](https://github.com/openstack/kolla-ansible/blob/master/ansible/library/kolla_toolbox.py): `ansible/library/kolla_toolbox.py`

### Ansible filters

- [Service filters](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/filters.py): `kolla_ansible/filters.py`
- [Service filter plugin](https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/services.py): `ansible/filter_plugins/services.py`
- [Address filters](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/kolla_address.py): `kolla_ansible/kolla_address.py`
- [Address filter plugin](https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/address.py): `ansible/filter_plugins/address.py`
- [URL formatting](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/kolla_url.py): `kolla_ansible/kolla_url.py`
- [Address context](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/put_address_in_context.py): `kolla_ansible/put_address_in_context.py`
- [Database shards](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/database_shards.py): `kolla_ansible/database_shards.py`
- [Database filter plugin](https://github.com/openstack/kolla-ansible/blob/master/ansible/filter_plugins/database.py): `ansible/filter_plugins/database.py`
- [Nova filters](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/nova_filters.py): `kolla_ansible/nova_filters.py`
- [Fluentd filters](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/fluentd_filters.py): `kolla_ansible/fluentd_filters.py`

### Password utilities

- [Password commands](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/genpwd.py): `kolla_ansible/cmd/genpwd.py`
- [Vault utilities](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/hashi_vault.py): `kolla_ansible/hashi_vault.py`
- [Read passwords](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/readpwd.py): `kolla_ansible/cmd/readpwd.py`
- [Write passwords](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/writepwd.py): `kolla_ansible/cmd/writepwd.py`
- [Merge passwords](https://github.com/openstack/kolla-ansible/blob/master/kolla_ansible/cmd/mergepwd.py): `kolla_ansible/cmd/mergepwd.py`

### Deployed cloud

- [Cloud services](https://github.com/openstack/kolla-ansible/tree/master/ansible): `ansible`
- [Infrastructure services](https://github.com/openstack/kolla-ansible/tree/master/ansible): `ansible`

### Other components

- **Operator**
- **Ansible**

## Connections

- Operator → Operations commands: invokes
- Operations commands → Ansible runner: runs playbooks (evidence: `kolla_ansible/cli/commands.py`)
- Ansible runner → Ansible: launches (evidence: `kolla_ansible/ansible.py`)
- Ansible → Container module: dispatches module
- Container module → Container worker: uses worker (evidence: `ansible/library/kolla_container.py`)
- Container module → Docker worker: uses backend (evidence: `ansible/library/kolla_container.py`)
- Container module → Podman worker: uses backend (evidence: `ansible/library/kolla_container.py`)
- Container worker → Systemd worker: uses systemd (evidence: `ansible/module_utils/kolla_container_worker.py`)
- Docker worker → Container worker: extends worker (evidence: `ansible/module_utils/kolla_docker_worker.py`)
- Podman worker → Container worker: extends worker (evidence: `ansible/module_utils/kolla_podman_worker.py`)
- Operations commands → Cloud services: deploys (evidence: `README.rst`)
- Operations commands → Infrastructure services: deploys (evidence: `README.rst`)
- Service filter plugin → Service filters: exposes (evidence: `ansible/filter_plugins/services.py`)
- Address filter plugin → Address filters: exposes (evidence: `ansible/filter_plugins/address.py`)
- Address filters → URL formatting: formats URLs (evidence: `kolla_ansible/kolla_url.py`)
- URL formatting → Address context: formats context (evidence: `kolla_ansible/kolla_url.py`)
- Database filter plugin → Database shards: exposes (evidence: `ansible/filter_plugins/database.py`)
- Read passwords → Vault utilities: reads vault (evidence: `kolla_ansible/cmd/readpwd.py`)
- Write passwords → Vault utilities: writes vault (evidence: `kolla_ansible/cmd/writepwd.py`)
- Operator → Password commands: generates secrets
- Operator → Read passwords: reads secrets
- Operator → Write passwords: writes secrets
- Operator → Merge passwords: merges secrets
