# ansible/galaxy-operator architecture

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

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

## Overview

##### Project Type & Purpose
- This is a Kubernetes Operator project (“Galaxy-Operator”) built with the Ansible Operator SDK.
- It provides three Custom Resource Definitions (CRDs) – Galaxy, GalaxyBackup, GalaxyRestore – and uses Ansible roles/playbooks to reconcile cluster state when those CRs are created or modified.
- It manages the full lifecycle of a Galaxy service deployment (Galaxy API, Web UI, Worker, Content services), plus backing up and restoring data (Postgres, Redis, object storage, etc.).

##### Top-Level Structure & Architectural Patterns
- `.ci` & `.github`: CI/CD pipelines and scripts that build/push Operator and related images.
- `config/`: Kubernetes manifests (CRDs, RBAC, Kustomize overlays) that define what the operator installs.
- `watches.yaml`: Tells the operator which CRDs to watch and which Ansible playbooks to run.
- `roles/` & `playbooks/`: Ansible roles and playbooks implementing reconciliation logic for Galaxy, backup, restore, plus common utility roles (Postgres, Redis, object storage).
- `molecule/`: Integration tests that validate the operator in a Kind cluster.

Architectural Pattern:
- Kubernetes Controller pattern (watch → reconcile → actuate).
- CRDs → Operator → Ansible engine → Kubernetes API.

##### Main Components
- Kubernetes Cluster (API Server, etcd)
- CRDs (Galaxy, GalaxyBackup, GalaxyRestore)
- Galaxy-Operator Pod
- Ansible Operator SDK (controller manager)
- Ansible engine + Watcher (from `watches.yaml`)
- Ansible Roles/Playbooks
- galaxy-api, galaxy-web, galaxy-worker, galaxy-content
- postgres, redis, backup, restore, common
- Managed Kubernetes Resources
- Deployments/StatefulSets (Galaxy API, Web, Worker, Postgres, Redis)
- Services, Ingress/Routes, PVCs, ConfigMaps, Secrets
- Jobs (backup/restore)
- External Dependencies
- Object storage (AWS S3, Azure Blob)
- Container registries (quay.io for images)

##### Relationships & Data Flows
- CRD event → Operator’s Controller Manager → Ansible engine
- Ansible playbooks perform tasks via Kubernetes API (create/update Deployments, Services, Secrets, PVCs, Jobs)
- Galaxy pods connect to Postgres and Redis services
- Backup jobs push data to object storage; Restore jobs pull data back into Postgres/PVCs
- Operator status is updated on the CR status sub-resource

##### Essential Elements
- Clear component labels (e.g., “Galaxy-Operator Pod”, “Postgres StatefulSet”).
- Callouts for key technologies: Ansible Operator SDK, Kubernetes API server, CRDs, Kustomize, Molecule tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kubernetes Cluster"
        direction TB
        API["API Server / etcd"]:::cluster

        subgraph "CRDs & Watches"
            direction TB
            GalaxyCRD["Galaxy CRD"]:::crd
            BackupCRD["GalaxyBackup CRD"]:::crd
            RestoreCRD["GalaxyRestore CRD"]:::crd
            Watches["watches.yaml"]:::operator
        end

        subgraph "Galaxy-Operator Pod"
            direction TB
            CM["Controller Manager\n(Ansible Operator SDK)"]:::operator
            Engine["Ansible Engine"]:::operator
        end

        subgraph "Ansible Roles/Playbooks"
            direction TB
            PB["galaxy.yaml\n(requirements.yml)"]:::operator
            subgraph "Galaxy App Roles"
                direction TB
                APIrole["roles/galaxy-api"]:::operator
                WebRole["roles/galaxy-web"]:::operator
                WorkerRole["roles/galaxy-worker"]:::operator
                ContentRole["roles/galaxy-content"]:::operator
                RouteRole["roles/galaxy-route"]:::operator
                ConfigRole["roles/galaxy-config"]:::operator
                StatusRole["roles/galaxy-status"]:::operator
                CommonRole["roles/common"]:::operator
            end
            subgraph "Backing Service Roles"
                direction TB
                PostgresRole["roles/postgres"]:::stateful
                RedisRole["roles/redis"]:::stateful
            end
            subgraph "Backup & Restore Roles"
                direction TB
                BackupRole["roles/backup"]:::operator
                RestoreRole["roles/restore"]:::operator
            end
        end

        GalaxyCRD -->|watches| CM
        BackupCRD -->|watches| CM
        RestoreCRD -->|watches| CM
        CM -->|reconcile| Engine
        Watches -->|configured| Engine

        Engine -->|runs| PB
        PB --> APIrole
        PB --> WebRole
        PB --> WorkerRole
        PB --> ContentRole
        PB --> RouteRole
        PB --> ConfigRole
        PB --> StatusRole
        PB --> CommonRole
        PB --> PostgresRole
        PB --> RedisRole
        PB --> BackupRole
        PB --> RestoreRole

        Engine -->|creates| Deploy["Deployments/StatefulSets"]:::workload
        Engine -->|creates| Services["Services/Ingress/Routes"]:::workload
        Engine -->|creates| PVC["PVCs"]:::stateful
        Engine -->|creates| ConfigMaps["ConfigMaps/Secrets"]:::workload
        Engine -->|creates| Jobs["Jobs (backup/restore)"]:::workload

        subgraph "Galaxy Application"
            direction TB
            GalaxyAPI["Galaxy API Deployment"]:::workload
            GalaxyWeb["Galaxy Web UI Deployment"]:::workload
            GalaxyWorker["Galaxy Worker Deployment"]:::workload
            GalaxyContent["Galaxy Content Service"]:::workload
            SvcAPI["Service"]:::workload
            SvcWeb["Service"]:::workload
            SvcWorker["Service"]:::workload
            SvcContent["Service"]:::workload
        end

        subgraph "Stateful Backing Services"
            direction TB
            PG["Postgres StatefulSet"]:::stateful
            PGPVC["Postgres PVC"]:::stateful
            REDIS["Redis StatefulSet"]:::stateful
            REDISPVC["Redis PVC"]:::stateful
        end

        Engine -->|creates| GalaxyAPI
        Engine -->|creates| GalaxyWeb
        Engine -->|creates| GalaxyWorker
        Engine -->|creates| GalaxyContent
        GalaxyAPI -->|connects to| PG
        GalaxyAPI -->|connects to| REDIS
        GalaxyWeb -->|connects to| PG
        GalaxyWeb -->|connects to| REDIS

        Jobs -->|Push to S3| externalS3
        Jobs -->|Pull from S3| externalS3

        externalReg["Container Registry\n(quay.io)"]:::external
        externalS3["Object Storage\n(S3/Azure Blob)"]:::external

        GalaxyAPI -->|Pull images| externalReg
        GalaxyWeb -->|Pull images| externalReg
    end

    %% Click Events
    click GalaxyCRD "https://github.com/ansible/galaxy-operator/blob/main/config/crd/bases/galaxy_v1beta1_galaxy_crd.yaml"
    click BackupCRD "https://github.com/ansible/galaxy-operator/blob/main/config/crd/bases/galaxy_v1beta1_galaxybackup_crd.yaml"
    click RestoreCRD "https://github.com/ansible/galaxy-operator/blob/main/config/crd/bases/galaxy_v1beta1_galaxyrestore_crd.yaml"
    click Watches "https://github.com/ansible/galaxy-operator/blob/main/watches.yaml"
    click CM "https://github.com/ansible/galaxy-operator/blob/main/config/manager/manager.yaml"
    click CM "https://github.com/ansible/galaxy-operator/blob/main/config/manager/controller_manager_config.yaml"
    click CM "https://github.com/ansible/galaxy-operator/tree/main/Dockerfile"
    click CM "https://github.com/ansible/galaxy-operator/blob/main/bundle.Dockerfile"
    click PB "https://github.com/ansible/galaxy-operator/blob/main/playbooks/galaxy.yaml"
    click PB "https://github.com/ansible/galaxy-operator/blob/main/requirements.yml"
    click APIrole "https://github.com/ansible/galaxy-operator/tree/main/roles/galaxy-api"
    click WebRole "https://github.com/ansible/galaxy-operator/tree/main/roles/galaxy-web"
    click WorkerRole "https://github.com/ansible/galaxy-operator/tree/main/roles/galaxy-worker"
    click ContentRole "https://github.com/ansible/galaxy-operator/tree/main/roles/galaxy-content"
    click PostgresRole "https://github.com/ansible/galaxy-operator/tree/main/roles/postgres"
    click RedisRole "https://github.com/ansible/galaxy-operator/tree/main/roles/redis"
    click BackupRole "https://github.com/ansible/galaxy-operator/tree/main/roles/backup"
    click RestoreRole "https://github.com/ansible/galaxy-operator/tree/main/roles/restore"
    click ci "https://github.com/ansible/galaxy-operator/tree/main/.ci/"
    click ci "https://github.com/ansible/galaxy-operator/blob/main/.github/workflows/build-operator-image.yaml"
    click ci "https://github.com/ansible/galaxy-operator/blob/main/.github/workflows/ci.yml"
    click molecule "https://github.com/ansible/galaxy-operator/tree/main/molecule/default/"
    click molecule "https://github.com/ansible/galaxy-operator/tree/main/molecule/kind/"

    %% Styles
    classDef crd fill:#D8BFD8,stroke:#333
    classDef operator fill:#ADD8E6,stroke:#333
    classDef workload fill:#98FB98,stroke:#333
    classDef stateful fill:#FFA500,stroke:#333
    classDef external fill:#D3D3D3,stroke:#333
    classDef cluster fill:#FFFFFF,stroke:#666,stroke-dasharray: 5 5
```
