# ansible/awx-operator architecture

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

- Interactive diagram: https://gitdiagram.com/ansible/awx-operator
- Repository: https://github.com/ansible/awx-operator

## Overview

AWX Operator reconciles Kubernetes custom resources into AWX deployments and manages their lifecycle. Its principal workflow is an administrator submitting an AWX resource, which the operator watches and handles through the AWX playbook and installer role. Separate custom-resource workflows cover backups, restores, and mesh ingress. The tree and README establish these capabilities and role boundaries; sampled source does not include the reconciliation implementation, so detailed call wiring is not asserted.

Main entry points: [`watches.yaml`](https://github.com/ansible/awx-operator/blob/devel/watches.yaml) (AWX Operator), [`roles/installer/tasks/main.yml`](https://github.com/ansible/awx-operator/blob/devel/roles/installer/tasks/main.yml) (AWX Installer), [`roles/restore/tasks/main.yml`](https://github.com/ansible/awx-operator/blob/devel/roles/restore/tasks/main.yml) (Restore Tasks), [`roles/mesh_ingress/tasks/main.yml`](https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/tasks/main.yml) (Mesh Ingress Tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconcile["AWX Reconciliation"]
  node_operator["AWX Operator<br/>[watches.yaml]"]
  node_awx_playbook["AWX Playbook<br/>[awx.yml]"]
  node_installer["AWX Installer<br/>[main.yml]"]
  node_deployment_templates["Deployment Templates"]
  node_postgres[("PostgreSQL<br/>[postgres.yaml.j2]")]
end

subgraph group_lifecycle["Lifecycle Operations"]
  node_backup_role["Backup Tasks<br/>[main.yml]"]
  node_backup_storage[("Backup Storage<br/>[backup_pvc.yml.j2]")]
  node_restore_role["Restore Tasks<br/>[main.yml]"]
  node_restore_awx["AWX Restore Object<br/>[awx_object.yml.j2]"]
end

subgraph group_network["Mesh Networking"]
  node_mesh_role["Mesh Ingress Tasks<br/>[main.yml]"]
  node_mesh_deployment["Mesh Deployment<br/>[deployment.yml.j2]"]
  node_receptor["Receptor Service<br/>[service.yml.j2]"]
end

subgraph group_cluster["Cluster Resources"]
  node_awx_cr["AWX Resource"]
  node_backup_cr["Backup Resource"]
  node_restore_cr["Restore Resource"]
  node_mesh_cr["Mesh Ingress Resource"]
end

node_admin(("Cluster Admin"))
node_kube["Kubernetes API"]

node_admin -->|"submits resources"| node_kube
node_kube -->|"stores"| node_awx_cr
node_kube -->|"notifies changes"| node_operator
node_operator -->|"dispatches"| node_awx_playbook
node_awx_playbook -->|"runs"| node_installer
node_installer -->|"renders workloads"| node_deployment_templates
node_installer -->|"renders database"| node_postgres
node_kube -->|"stores"| node_backup_cr
node_kube -->|"stores"| node_restore_cr
node_kube -->|"stores"| node_mesh_cr
node_operator -->|"dispatches"| node_backup_role
node_operator -->|"dispatches"| node_restore_role
node_operator -->|"dispatches"| node_mesh_role
node_backup_role -->|"creates backup volume"| node_backup_storage
node_restore_role -->|"reads backup"| node_backup_storage
node_restore_role -->|"renders resource"| node_restore_awx
node_mesh_role -->|"renders deployment"| node_mesh_deployment
node_mesh_role -->|"renders service"| node_receptor

click node_awx_cr "https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxs.yaml"
click node_operator "https://github.com/ansible/awx-operator/blob/devel/watches.yaml"
click node_awx_playbook "https://github.com/ansible/awx-operator/blob/devel/playbooks/awx.yml"
click node_installer "https://github.com/ansible/awx-operator/blob/devel/roles/installer/tasks/main.yml"
click node_deployment_templates "https://github.com/ansible/awx-operator/tree/devel/roles/installer/templates/deployments"
click node_postgres "https://github.com/ansible/awx-operator/blob/devel/roles/installer/templates/statefulsets/postgres.yaml.j2"
click node_backup_cr "https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxbackups.yaml"
click node_backup_role "https://github.com/ansible/awx-operator/blob/devel/roles/backup/tasks/main.yml"
click node_backup_storage "https://github.com/ansible/awx-operator/blob/devel/roles/backup/templates/backup_pvc.yml.j2"
click node_restore_cr "https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxrestores.yaml"
click node_restore_role "https://github.com/ansible/awx-operator/blob/devel/roles/restore/tasks/main.yml"
click node_restore_awx "https://github.com/ansible/awx-operator/blob/devel/roles/restore/templates/awx_object.yml.j2"
click node_mesh_cr "https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxmeshingresses.yaml"
click node_mesh_role "https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/tasks/main.yml"
click node_mesh_deployment "https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/templates/deployment.yml.j2"
click node_receptor "https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/templates/service.yml.j2"

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_operator,node_awx_playbook,node_installer,node_deployment_templates,node_postgres toneBlue
class node_backup_role,node_backup_storage,node_restore_role,node_restore_awx toneAmber
class node_mesh_role,node_mesh_deployment,node_receptor,node_kube toneMint
class node_awx_cr,node_backup_cr,node_restore_cr,node_mesh_cr toneRose
class node_admin toneIndigo
```

## Components

### AWX Reconciliation

- [AWX Operator](https://github.com/ansible/awx-operator/blob/devel/watches.yaml): `watches.yaml`
- [AWX Playbook](https://github.com/ansible/awx-operator/blob/devel/playbooks/awx.yml): `playbooks/awx.yml`
- [AWX Installer](https://github.com/ansible/awx-operator/blob/devel/roles/installer/tasks/main.yml): `roles/installer/tasks/main.yml`
- [Deployment Templates](https://github.com/ansible/awx-operator/tree/devel/roles/installer/templates/deployments): `roles/installer/templates/deployments`
- [PostgreSQL](https://github.com/ansible/awx-operator/blob/devel/roles/installer/templates/statefulsets/postgres.yaml.j2): `roles/installer/templates/statefulsets/postgres.yaml.j2`

### Lifecycle Operations

- [Backup Tasks](https://github.com/ansible/awx-operator/blob/devel/roles/backup/tasks/main.yml): `roles/backup/tasks/main.yml`
- [Backup Storage](https://github.com/ansible/awx-operator/blob/devel/roles/backup/templates/backup_pvc.yml.j2): `roles/backup/templates/backup_pvc.yml.j2`
- [Restore Tasks](https://github.com/ansible/awx-operator/blob/devel/roles/restore/tasks/main.yml): `roles/restore/tasks/main.yml`
- [AWX Restore Object](https://github.com/ansible/awx-operator/blob/devel/roles/restore/templates/awx_object.yml.j2): `roles/restore/templates/awx_object.yml.j2`

### Mesh Networking

- [Mesh Ingress Tasks](https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/tasks/main.yml): `roles/mesh_ingress/tasks/main.yml`
- [Mesh Deployment](https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/templates/deployment.yml.j2): `roles/mesh_ingress/templates/deployment.yml.j2`
- [Receptor Service](https://github.com/ansible/awx-operator/blob/devel/roles/mesh_ingress/templates/service.yml.j2): `roles/mesh_ingress/templates/service.yml.j2`

### Cluster Resources

- [AWX Resource](https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxs.yaml): `config/crd/bases/awx.ansible.com_awxs.yaml`
- [Backup Resource](https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxbackups.yaml): `config/crd/bases/awx.ansible.com_awxbackups.yaml`
- [Restore Resource](https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxrestores.yaml): `config/crd/bases/awx.ansible.com_awxrestores.yaml`
- [Mesh Ingress Resource](https://github.com/ansible/awx-operator/blob/devel/config/crd/bases/awx.ansible.com_awxmeshingresses.yaml): `config/crd/bases/awx.ansible.com_awxmeshingresses.yaml`

### Other components

- **Cluster Admin**
- **Kubernetes API**

## Connections

- Cluster Admin → Kubernetes API: submits resources
- Kubernetes API → AWX Resource: stores
- Kubernetes API → AWX Operator: notifies changes
- AWX Operator → AWX Playbook: dispatches
- AWX Playbook → AWX Installer: runs
- AWX Installer → Deployment Templates: renders workloads
- AWX Installer → PostgreSQL: renders database
- Kubernetes API → Backup Resource: stores
- Kubernetes API → Restore Resource: stores
- Kubernetes API → Mesh Ingress Resource: stores
- AWX Operator → Backup Tasks: dispatches
- AWX Operator → Restore Tasks: dispatches
- AWX Operator → Mesh Ingress Tasks: dispatches
- Backup Tasks → Backup Storage: creates backup volume
- Restore Tasks → Backup Storage: reads backup
- Restore Tasks → AWX Restore Object: renders resource
- Mesh Ingress Tasks → Mesh Deployment: renders deployment
- Mesh Ingress Tasks → Receptor Service: renders service