# rhobs/observability-operator architecture

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

- Interactive diagram: https://gitdiagram.com/rhobs/observability-operator
- Repository: https://github.com/rhobs/observability-operator

## Overview

The Observability Operator manages Kubernetes monitoring stacks and related observability capabilities through custom resources. A user creates CRDs; the manager registers controllers that reconcile desired resources, status, and cleanup. The main branches cover monitoring/alerting, Thanos query, tracing/logging installation, and console UI plugins. A separate must-gather command collects cluster diagnostics. Edges follow explicit README or excerpted wiring; unsampled controller details are represented only where the SOURCE INDEX supports their modules.

Main entry points: [`pkg/operator/operator.go`](https://github.com/rhobs/observability-operator/blob/main/pkg/operator/operator.go) (Controller manager), [`pkg/controllers/monitoring/monitoring-stack/controller.go`](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/controller.go) (Stack reconciler), [`pkg/controllers/monitoring/thanos-querier/controller.go`](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/thanos-querier/controller.go) (Thanos reconciler), [`pkg/controllers/observability/observability_controller.go`](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/observability_controller.go) (Capability installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Operator runtime"]
  node_entry["Operator entrypoint<br/>[main.go]"]
  node_manager["Controller manager<br/>[operator.go]"]
  node_apis["Custom resource APIs"]
end

subgraph group_monitoring["Monitoring controllers"]
  node_monitoring_cr["MonitoringStack API<br/>[types.go]"]
  node_stack_controller["Stack reconciler<br/>[controller.go]"]
  node_stack_components["Stack components<br/>[components.go]"]
  node_alertmanager["Alertmanager resources<br/>[alertmanager.go]"]
  node_querier_controller["Thanos reconciler<br/>[controller.go]"]
  node_querier_components["Thanos components<br/>[components.go]"]
end

subgraph group_observability["Observability capabilities"]
  node_observability_cr["Installer API"]
  node_installer["Capability installer"]
  node_capability_reconcilers["Capability reconcilers<br/>[reconcilers.go]"]
  node_tempo["Tempo components"]
  node_otel["OpenTelemetry components<br/>[otel_components.go]"]
  node_uiplugin_api["UIPlugin API<br/>[types.go]"]
  node_plugin_controller["Plugin reconciler<br/>[controller.go]"]
  node_plugin_components["Plugin resources<br/>[components.go]"]
  node_plugin_monitoring["Monitoring UI<br/>[monitoring.go]"]
  node_plugin_extensions["UI extensions<br/>[accelerators.go]"]
end

subgraph group_diagnostics["Cluster diagnostics"]
  node_gather_cli["Must-gather command<br/>[main.go]"]
  node_gather["Gather orchestrator<br/>[gather.go]"]
  node_collector["Monitoring collector<br/>[collector.go]"]
  node_gather_client["Kubernetes client<br/>[client.go]"]
end

node_user(("Cluster admin"))
node_cluster[("Kubernetes API")]
node_gather_user(("Support engineer"))
node_bundle["Collected diagnostics"]

node_user -->|"starts operator"| node_entry
node_entry -->|"configures and starts"| node_manager
node_manager -->|"registers APIs"| node_monitoring_cr
node_manager -->|"registers controller"| node_stack_controller
node_manager -->|"registers controller"| node_querier_controller
node_manager -->|"registers controller"| node_installer
node_manager -->|"registers controller"| node_plugin_controller
node_user -->|"submits desired state"| node_monitoring_cr
node_monitoring_cr -.->|"watches resources"| node_stack_controller
node_stack_controller -->|"builds reconcilers"| node_stack_components
node_stack_components -->|"creates resources"| node_alertmanager
node_stack_controller -.->|"reconciles resources"| node_cluster
node_user -.->|"requests query service"| node_querier_controller
node_querier_controller -.->|"reconciles components"| node_querier_components
node_querier_controller -.->|"reads and writes"| node_cluster
node_user -->|"submits capabilities"| node_observability_cr
node_observability_cr -.->|"triggers reconcile"| node_installer
node_installer -->|"delegates reconcile"| node_capability_reconcilers
node_capability_reconcilers -.->|"reconciles tracing"| node_tempo
node_capability_reconcilers -.->|"reconciles telemetry"| node_otel
node_installer -->|"reads and patches"| node_cluster
node_user -.->|"configures plugins"| node_uiplugin_api
node_uiplugin_api -.->|"triggers reconcile"| node_plugin_controller
node_plugin_controller -.->|"builds plugin resources"| node_plugin_components
node_plugin_controller -->|"registers console plugin"| node_cluster
node_plugin_components -.->|"adds monitoring support"| node_plugin_monitoring
node_plugin_components -.->|"adds UI features"| node_plugin_extensions
node_gather_user -->|"runs collection"| node_gather_cli
node_gather_cli -->|"creates and runs"| node_gather
node_gather -->|"runs collector"| node_collector
node_gather -->|"creates Kubernetes client"| node_gather_client
node_collector -->|"queries cluster"| node_gather_client
node_gather_client -->|"lists and proxies"| node_cluster
node_collector -.->|"writes diagnostics"| node_bundle

click node_entry "https://github.com/rhobs/observability-operator/blob/main/cmd/operator/main.go"
click node_manager "https://github.com/rhobs/observability-operator/blob/main/pkg/operator/operator.go"
click node_apis "https://github.com/rhobs/observability-operator/tree/main/pkg/apis"
click node_monitoring_cr "https://github.com/rhobs/observability-operator/blob/main/pkg/apis/monitoring/v1alpha1/types.go"
click node_stack_controller "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/controller.go"
click node_stack_components "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/components.go"
click node_alertmanager "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/alertmanager.go"
click node_querier_controller "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/thanos-querier/controller.go"
click node_querier_components "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/thanos-querier/components.go"
click node_observability_cr "https://github.com/rhobs/observability-operator/tree/main/pkg/apis/observability/v1alpha1"
click node_installer "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/observability_controller.go"
click node_capability_reconcilers "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/reconcilers.go"
click node_tempo "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/tempo_components.go"
click node_otel "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/otel_components.go"
click node_uiplugin_api "https://github.com/rhobs/observability-operator/blob/main/pkg/apis/uiplugin/v1alpha1/types.go"
click node_plugin_controller "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/controller.go"
click node_plugin_components "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/components.go"
click node_plugin_monitoring "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/monitoring.go"
click node_plugin_extensions "https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/accelerators.go"
click node_gather_cli "https://github.com/rhobs/observability-operator/blob/main/must-gather/cmd/main.go"
click node_gather "https://github.com/rhobs/observability-operator/blob/main/must-gather/gather.go"
click node_collector "https://github.com/rhobs/observability-operator/blob/main/must-gather/internal/monitoring/collector.go"
click node_gather_client "https://github.com/rhobs/observability-operator/blob/main/must-gather/internal/client/client.go"

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_entry,node_manager,node_apis toneBlue
class node_monitoring_cr,node_stack_controller,node_stack_components,node_alertmanager,node_querier_controller,node_querier_components,node_cluster toneAmber
class node_observability_cr,node_installer,node_capability_reconcilers,node_tempo,node_otel,node_uiplugin_api,node_plugin_controller,node_plugin_components,node_plugin_monitoring,node_plugin_extensions toneMint
class node_gather_cli,node_gather,node_collector,node_gather_client toneRose
class node_user,node_gather_user,node_bundle toneIndigo
```

## Components

### Operator runtime

- [Operator entrypoint](https://github.com/rhobs/observability-operator/blob/main/cmd/operator/main.go): `cmd/operator/main.go`
- [Controller manager](https://github.com/rhobs/observability-operator/blob/main/pkg/operator/operator.go): `pkg/operator/operator.go`
- [Custom resource APIs](https://github.com/rhobs/observability-operator/tree/main/pkg/apis): `pkg/apis`

### Monitoring controllers

- [MonitoringStack API](https://github.com/rhobs/observability-operator/blob/main/pkg/apis/monitoring/v1alpha1/types.go): `pkg/apis/monitoring/v1alpha1/types.go`
- [Stack reconciler](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/controller.go): `pkg/controllers/monitoring/monitoring-stack/controller.go`
- [Stack components](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/components.go): `pkg/controllers/monitoring/monitoring-stack/components.go`
- [Alertmanager resources](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/monitoring-stack/alertmanager.go): `pkg/controllers/monitoring/monitoring-stack/alertmanager.go`
- [Thanos reconciler](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/thanos-querier/controller.go): `pkg/controllers/monitoring/thanos-querier/controller.go`
- [Thanos components](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/monitoring/thanos-querier/components.go): `pkg/controllers/monitoring/thanos-querier/components.go`

### Observability capabilities

- [Installer API](https://github.com/rhobs/observability-operator/tree/main/pkg/apis/observability/v1alpha1): `pkg/apis/observability/v1alpha1`
- [Capability installer](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/observability_controller.go): `pkg/controllers/observability/observability_controller.go`
- [Capability reconcilers](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/reconcilers.go): `pkg/controllers/observability/reconcilers.go`
- [Tempo components](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/tempo_components.go): `pkg/controllers/observability/tempo_components.go`
- [OpenTelemetry components](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/observability/otel_components.go): `pkg/controllers/observability/otel_components.go`
- [UIPlugin API](https://github.com/rhobs/observability-operator/blob/main/pkg/apis/uiplugin/v1alpha1/types.go): `pkg/apis/uiplugin/v1alpha1/types.go`
- [Plugin reconciler](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/controller.go): `pkg/controllers/uiplugin/controller.go`
- [Plugin resources](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/components.go): `pkg/controllers/uiplugin/components.go`
- [Monitoring UI](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/monitoring.go): `pkg/controllers/uiplugin/monitoring.go`
- [UI extensions](https://github.com/rhobs/observability-operator/blob/main/pkg/controllers/uiplugin/accelerators.go): `pkg/controllers/uiplugin/accelerators.go`

### Cluster diagnostics

- [Must-gather command](https://github.com/rhobs/observability-operator/blob/main/must-gather/cmd/main.go): `must-gather/cmd/main.go`
- [Gather orchestrator](https://github.com/rhobs/observability-operator/blob/main/must-gather/gather.go): `must-gather/gather.go`
- [Monitoring collector](https://github.com/rhobs/observability-operator/blob/main/must-gather/internal/monitoring/collector.go): `must-gather/internal/monitoring/collector.go`
- [Kubernetes client](https://github.com/rhobs/observability-operator/blob/main/must-gather/internal/client/client.go): `must-gather/internal/client/client.go`

### Other components

- **Cluster admin**
- **Kubernetes API**
- **Support engineer**
- **Collected diagnostics**

## Connections

- Cluster admin → Operator entrypoint: starts operator (evidence: `README.md`)
- Operator entrypoint → Controller manager: configures and starts (evidence: `cmd/operator/main.go`)
- Controller manager → MonitoringStack API: registers APIs
- Controller manager → Stack reconciler: registers controller (evidence: `pkg/operator/operator.go`)
- Controller manager → Thanos reconciler: registers controller (evidence: `pkg/operator/operator.go`)
- Controller manager → Capability installer: registers controller (evidence: `pkg/operator/operator.go`)
- Controller manager → Plugin reconciler: registers controller (evidence: `pkg/operator/operator.go`)
- Cluster admin → MonitoringStack API: submits desired state (evidence: `README.md`)
- MonitoringStack API → Stack reconciler: watches resources
- Stack reconciler → Stack components: builds reconcilers (evidence: `pkg/controllers/monitoring/monitoring-stack/controller.go`)
- Stack components → Alertmanager resources: creates resources (evidence: `pkg/controllers/monitoring/monitoring-stack/components.go`)
- Stack reconciler → Kubernetes API: reconciles resources
- Cluster admin → Thanos reconciler: requests query service
- Thanos reconciler → Thanos components: reconciles components
- Thanos reconciler → Kubernetes API: reads and writes
- Cluster admin → Installer API: submits capabilities (evidence: `README.md`)
- Installer API → Capability installer: triggers reconcile (evidence: `pkg/controllers/observability/observability_controller.go`)
- Capability installer → Capability reconcilers: delegates reconcile (evidence: `pkg/controllers/observability/observability_controller.go`)
- Capability reconcilers → Tempo components: reconciles tracing
- Capability reconcilers → OpenTelemetry components: reconciles telemetry
- Capability installer → Kubernetes API: reads and patches (evidence: `pkg/controllers/observability/observability_controller.go`)
- Cluster admin → UIPlugin API: configures plugins
- UIPlugin API → Plugin reconciler: triggers reconcile
- Plugin reconciler → Plugin resources: builds plugin resources
- Plugin reconciler → Kubernetes API: registers console plugin (evidence: `pkg/controllers/uiplugin/controller.go`)
- Plugin resources → Monitoring UI: adds monitoring support
- Plugin resources → UI extensions: adds UI features
- Support engineer → Must-gather command: runs collection (evidence: `must-gather/cmd/main.go`)
- Must-gather command → Gather orchestrator: creates and runs (evidence: `must-gather/cmd/main.go`)
- Gather orchestrator → Monitoring collector: runs collector (evidence: `must-gather/gather.go`)
- Gather orchestrator → Kubernetes client: creates Kubernetes client (evidence: `must-gather/gather.go`)
- Monitoring collector → Kubernetes client: queries cluster (evidence: `must-gather/internal/monitoring/collector.go`)
- Kubernetes client → Kubernetes API: lists and proxies (evidence: `must-gather/internal/client/client.go`)
- Monitoring collector → Collected diagnostics: writes diagnostics
