# rabbitmq/cluster-operator architecture

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

- Interactive diagram: https://gitdiagram.com/rabbitmq/cluster-operator
- Repository: https://github.com/rabbitmq/cluster-operator

## Overview

##### Project type and purpose
- This is a Kubernetes Operator written in Go, specifically the RabbitMQ Cluster Kubernetes Operator.
- Its purpose is to provide a custom controller plus CRD definitions to manage the full lifecycle (create, scale, upgrade, shutdown) of RabbitMQ clusters running on Kubernetes.

##### File structure
- Top-level directories:
- api/v1beta1: CRD schema and generated code for RabbitMQCluster custom resource
- controllers: reconciliation logic broken into multiple Go source files (each handling part of the resource lifecycle)
- config: kustomize overlays for CRD installation, RBAC, manager Deployment, namespace, samples, and installation
- internal: helper packages (metadata, resource builders, scaling, status, promtool, etc.)
- observability: Grafana dashboards, Prometheus rules and monitors for metrics collection and alerting
- olm: Operator Lifecycle Manager (OLM) bundle, assets, templates, tests
- bin: a Kubectl plugin (“kubectl-rabbitmq”) and its tests
- pkg: profiling support (pprof)
- hack, scripts: utility scripts for code generation, notices, version printing, testing
- system_tests, olm/test: E2E and integration tests
- Configuration files:
- Dockerfile, Makefile, PROJECT: build and metadata
- .github/workflows and dependabot, release pipelines
- go.mod, go.sum: module dependencies

##### README for additional insights
- The operator installs via applying bundled YAML (CRDs + Deployment + RBAC)
- Relies on controller-runtime from Kubernetes SIGs
- Integrates with Prometheus/Alertmanager and Grafana via ServiceMonitor/PodMonitor, dashboards
- Supports non-strict semver and OLM packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        APIServer["Kubernetes API Server"]:::k8s
        APIType["RabbitMQCluster CRD"]:::api
        Operator["Operator Deployment\n(Controller Manager)"]:::controller

        APIServer -->|"CRD Registered"| APIType
        APIType -->|"watch"| Operator

        subgraph "Controller Manager Components"
            direction TB
            Reconciler["Reconcile Loop"]:::controller
            Controllers["Controller Logic"]:::controller
            Metadata["Metadata Helper"]:::internal
            ResourceBuilders["Resource Builders"]:::internal
            Scaling["Scaling Logic"]:::internal
            Status["Status Computation"]:::internal
            Promtool["Promtool Integration"]:::internal
        end

        Operator --> Reconciler
        Reconciler --> Controllers
        Controllers --> Metadata
        Controllers --> ResourceBuilders
        Controllers --> Scaling
        Controllers --> Status
        Controllers --> Promtool
        Controllers --> APIServer
    end

    %% Data Plane
    subgraph "Data Plane"
        direction TB
        StatefulSet["StatefulSet"]:::data
        Services["Services\n(headless, client)"]:::data
        Configs["ConfigMaps / Secrets"]:::data
        Pods["RabbitMQ Pods"]:::data

        Operator -->|"apply"| StatefulSet
        Operator -->|"apply"| Services
        Operator -->|"apply"| Configs
        StatefulSet --> Pods
        Services --> Pods
        Configs --> Pods
    end

    %% Observability
    subgraph "Observability Stack"
        direction TB
        ServiceMonitor["ServiceMonitor / PodMonitor"]:::observability
        Prometheus["Prometheus"]:::observability
        Alertmanager["Alertmanager"]:::observability
        GrafanaDash["Grafana Dashboards"]:::observability

        Pods -->|"metrics"| ServiceMonitor
        ServiceMonitor -->|"scrape"| Prometheus
        Prometheus -->|"alert rules"| Alertmanager
        Prometheus -->|"visualization data"| GrafanaDash
    end

    %% Packaging / OLM
    subgraph "Packaging / OLM"
        direction TB
        Catalog["OLM Catalog"]:::packaging
        Subscription["OLM Subscription"]:::packaging
        Bundle["OLM Bundle & Assets"]:::packaging
        OLMTests["OLM Integration Tests"]:::packaging

        Catalog --> Subscription
        Subscription -->|"deploy"| APIType
        Subscription -->|"deploy"| Operator
        Bundle --> Subscription
    end

    %% CLI Extension
    subgraph "CLI Extension"
        direction TB
        CLI["kubectl-rabbitmq CLI Plugin"]:::cli
        CLI -->|"uses CRD"| APIServer
    end

    %% Testing & Utilities
    subgraph "Tests & Utilities"
        direction TB
        SysTests["E2E & Integration Tests"]:::tests
        Hack["Utility Scripts\n(hack)"]:::utility
        Scripts["Utility Scripts\n(scripts)"]:::utility
        Profiling["Profiling Support\n(pprof)"]:::utility
        Config["Kustomize Configuration"]:::config

        SysTests --> Operator
        OLMTests --> Subscription
        Hack -->|"code gen"| Operator
        Scripts -->|"version & notices"| Operator
        Profiling --> Operator
        Config -->|"install manifests"| APIServer
    end

    %% Build & Metadata Files
    BuildFiles["Dockerfile, Makefile,\nPROJECT, go.mod"]:::build
    BuildFiles --> Operator

    %% Click Events
    click APIType "https://github.com/rabbitmq/cluster-operator/tree/main/api/v1beta1"
    click Controllers "https://github.com/rabbitmq/cluster-operator/tree/main/controllers"
    click Config "https://github.com/rabbitmq/cluster-operator/tree/main/config"
    click Metadata "https://github.com/rabbitmq/cluster-operator/tree/main/internal/metadata"
    click ResourceBuilders "https://github.com/rabbitmq/cluster-operator/tree/main/internal/resource"
    click Scaling "https://github.com/rabbitmq/cluster-operator/tree/main/internal/scaling"
    click Status "https://github.com/rabbitmq/cluster-operator/tree/main/internal/status"
    click Promtool "https://github.com/rabbitmq/cluster-operator/tree/main/internal/promtool"
    click GrafanaDash "https://github.com/rabbitmq/cluster-operator/tree/main/observability/grafana/dashboards"
    click Prometheus "https://github.com/rabbitmq/cluster-operator/tree/main/observability/prometheus"
    click Bundle "https://github.com/rabbitmq/cluster-operator/tree/main/olm"
    click CLI "https://github.com/rabbitmq/cluster-operator/tree/main/bin/kubectl-rabbitmq"
    click Profiling "https://github.com/rabbitmq/cluster-operator/tree/main/pkg/profiling"
    click SysTests "https://github.com/rabbitmq/cluster-operator/tree/main/system_tests"
    click OLMTests "https://github.com/rabbitmq/cluster-operator/tree/main/olm/test"
    click Hack "https://github.com/rabbitmq/cluster-operator/tree/main/hack"
    click Scripts "https://github.com/rabbitmq/cluster-operator/tree/main/scripts"
    click Main "https://github.com/rabbitmq/cluster-operator/blob/main/main.go"
    click BuildFiles "https://github.com/rabbitmq/cluster-operator/tree/main/Dockerfile"

    %% Styles
    classDef k8s fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef api fill:#ffe4e1,stroke:#d35400,stroke-width:1px
    classDef controller fill:#e6e6fa,stroke:#5d4c86,stroke-width:1px
    classDef internal fill:#f5f5dc,stroke:#9a7d0a,stroke-width:1px
    classDef data fill:#e0ffff,stroke:#138d75,stroke-width:1px
    classDef observability fill:#fffacd,stroke:#f39c12,stroke-width:1px
    classDef packaging fill:#f0fff0,stroke:#27ae60,stroke-width:1px
    classDef cli fill:#fbeee6,stroke:#c0392b,stroke-width:1px
    classDef tests fill:#faf0e6,stroke:#7b1fa2,stroke-width:1px
    classDef utility fill:#f0f8ff,stroke:#2980b9,stroke-width:1px
    classDef config fill:#f9e79f,stroke:#b9770e,stroke-width:1px
    classDef build fill:#d5f5e3,stroke:#2ecc71,stroke-width:1px
```
