# stolostron/multicluster-observability-operator architecture

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

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

## Overview

This repository implements Open Cluster Management Observability: operators configure hub and managed-cluster monitoring, managed-cluster collectors send metrics to the hub, and hub services expose data for dashboards and queries. The main workflow runs from MCO orchestration through addon distribution and endpoint collection to the observability API; the RBAC query proxy and dashboard loader provide separate access paths. The README documents several external data-plane components whose implementations are outside this repository. Links reflect README statements or shown source references; unsampled components are represented only where documented capabilities support them.

Main entry points: [`operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go`](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go) (MCO Operator), [`operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go`](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go) (Endpoint Operator), [`proxy/pkg/proxy/proxy.go`](https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/proxy/proxy.go) (RBAC Query Proxy), [`collectors/metrics/cmd/metrics-collector/main.go`](https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/cmd/metrics-collector/main.go) (Metrics Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Hub Orchestration"]
  node_mco["MCO Operator"]
  node_placement["Addon Placement"]
end

subgraph group_collection["Cluster Collection"]
  node_endpoint["Endpoint Operator"]
  node_mcoa["MCOA Agent"]
  node_collector["Metrics Collector<br/>[main.go]"]
  node_forwarder["Metrics Forwarder<br/>[forwarder.go]"]
  node_metricsclient["Metrics Client<br/>[metricsclient.go]"]
  node_cmo["Prometheus And CMO"]
end

subgraph group_access["Query And Dashboards"]
  node_proxy["RBAC Query Proxy<br/>[proxy.go]"]
  node_informer["Cluster Informer<br/>[informer.go]"]
  node_modifier["Query Modifier<br/>[modifier.go]"]
  node_grafana["Grafana"]
  node_dashboardloader["Dashboard Loader"]
end

subgraph group_services["Observability Services"]
  node_api["Observatorium API"]
  node_thanos["Thanos Ecosystem"]
  node_objectstore[("Object Storage")]
  node_alertmanager["Alertmanager"]
end

subgraph group_analytics["Analytics And Status"]
  node_analytics["Rightsizing Analytics"]
  node_status["Operator Status"]
  node_endpointstatus["Endpoint Status"]
end

node_admin(("Cluster Admin"))
node_externalendpoint["External Endpoint"]
node_browser(("Web Browser"))

node_admin -.->|"configures"| node_mco
node_mco -->|"orchestrates"| node_placement
node_placement -->|"distributes addon"| node_endpoint
node_mco -->|"deploys data plane"| node_api
node_endpoint -->|"configures"| node_collector
node_endpoint -->|"configures monitoring"| node_cmo
node_mcoa -->|"reconciles config"| node_cmo
node_collector -->|"starts workers"| node_forwarder
node_forwarder -->|"uses client"| node_metricsclient
node_collector -->|"remote writes"| node_api
node_cmo -->|"forwards alerts"| node_alertmanager
node_api -->|"forwards requests"| node_thanos
node_api -.->|"remote writes"| node_externalendpoint
node_thanos -->|"stores data"| node_objectstore
node_thanos -->|"sends alerts"| node_alertmanager
node_browser -->|"accesses"| node_grafana
node_grafana -->|"queries via"| node_proxy
node_proxy -->|"proxies queries"| node_api
node_proxy -->|"uses cluster data"| node_informer
node_proxy -->|"modifies queries"| node_modifier
node_dashboardloader -->|"updates dashboards"| node_grafana
node_mco -->|"registers controller"| node_analytics
node_mco -->|"registers controller"| node_status
node_endpoint -->|"reports conditions"| node_endpointstatus

click node_mco "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go"
click node_placement "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/placementrule/placementrule_controller.go"
click node_endpoint "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go"
click node_mcoa "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/mcoa/mcoa_agent_controller.go"
click node_collector "https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/cmd/metrics-collector/main.go"
click node_forwarder "https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/pkg/forwarder/forwarder.go"
click node_metricsclient "https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/pkg/metricsclient/metricsclient.go"
click node_proxy "https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/proxy/proxy.go"
click node_informer "https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/informer/informer.go"
click node_modifier "https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/metricquery/modifier.go"
click node_dashboardloader "https://github.com/stolostron/multicluster-observability-operator/blob/main/loaders/dashboards/pkg/controller/dashboard_controller.go"
click node_analytics "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/analytics/rightsizing/rightsizing_controller.go"
click node_status "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/status/status_controller.go"
click node_endpointstatus "https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/status/status_controller.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_mco,node_placement,node_browser toneBlue
class node_endpoint,node_mcoa,node_collector,node_forwarder,node_metricsclient,node_cmo toneAmber
class node_proxy,node_informer,node_modifier,node_grafana,node_dashboardloader toneMint
class node_api,node_thanos,node_objectstore,node_alertmanager toneRose
class node_analytics,node_status,node_endpointstatus,node_admin,node_externalendpoint toneIndigo
```

## Components

### Hub Orchestration

- [MCO Operator](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go): `operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go`
- [Addon Placement](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/placementrule/placementrule_controller.go): `operators/multiclusterobservability/controllers/placementrule/placementrule_controller.go`

### Cluster Collection

- [Endpoint Operator](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go): `operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go`
- [MCOA Agent](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/mcoa/mcoa_agent_controller.go): `operators/endpointmetrics/controllers/mcoa/mcoa_agent_controller.go`
- [Metrics Collector](https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/cmd/metrics-collector/main.go): `collectors/metrics/cmd/metrics-collector/main.go`
- [Metrics Forwarder](https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/pkg/forwarder/forwarder.go): `collectors/metrics/pkg/forwarder/forwarder.go`
- [Metrics Client](https://github.com/stolostron/multicluster-observability-operator/blob/main/collectors/metrics/pkg/metricsclient/metricsclient.go): `collectors/metrics/pkg/metricsclient/metricsclient.go`
- **Prometheus And CMO**

### Query And Dashboards

- [RBAC Query Proxy](https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/proxy/proxy.go): `proxy/pkg/proxy/proxy.go`
- [Cluster Informer](https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/informer/informer.go): `proxy/pkg/informer/informer.go`
- [Query Modifier](https://github.com/stolostron/multicluster-observability-operator/blob/main/proxy/pkg/metricquery/modifier.go): `proxy/pkg/metricquery/modifier.go`
- **Grafana**
- [Dashboard Loader](https://github.com/stolostron/multicluster-observability-operator/blob/main/loaders/dashboards/pkg/controller/dashboard_controller.go): `loaders/dashboards/pkg/controller/dashboard_controller.go`

### Observability Services

- **Observatorium API**
- **Thanos Ecosystem**
- **Object Storage**
- **Alertmanager**

### Analytics And Status

- [Rightsizing Analytics](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/analytics/rightsizing/rightsizing_controller.go): `operators/multiclusterobservability/controllers/analytics/rightsizing/rightsizing_controller.go`
- [Operator Status](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/multiclusterobservability/controllers/status/status_controller.go): `operators/multiclusterobservability/controllers/status/status_controller.go`
- [Endpoint Status](https://github.com/stolostron/multicluster-observability-operator/blob/main/operators/endpointmetrics/controllers/status/status_controller.go): `operators/endpointmetrics/controllers/status/status_controller.go`

### Other components

- **Cluster Admin**
- **External Endpoint**
- **Web Browser**

## Connections

- Cluster Admin → MCO Operator: configures (evidence: `README.md`)
- MCO Operator → Addon Placement: orchestrates (evidence: `operators/multiclusterobservability/controllers/multiclusterobservability/multiclusterobservability_controller.go`)
- Addon Placement → Endpoint Operator: distributes addon (evidence: `README.md`)
- MCO Operator → Observatorium API: deploys data plane (evidence: `README.md`)
- Endpoint Operator → Metrics Collector: configures (evidence: `operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go`)
- Endpoint Operator → Prometheus And CMO: configures monitoring (evidence: `README.md`)
- MCOA Agent → Prometheus And CMO: reconciles config (evidence: `operators/endpointmetrics/controllers/mcoa/mcoa_agent_controller.go`)
- Metrics Collector → Metrics Forwarder: starts workers (evidence: `collectors/metrics/cmd/metrics-collector/main.go`)
- Metrics Forwarder → Metrics Client: uses client (evidence: `collectors/metrics/pkg/forwarder/forwarder.go`)
- Metrics Collector → Observatorium API: remote writes (evidence: `README.md`)
- Prometheus And CMO → Alertmanager: forwards alerts (evidence: `README.md`)
- Observatorium API → Thanos Ecosystem: forwards requests (evidence: `README.md`)
- Observatorium API → External Endpoint: remote writes (evidence: `README.md`)
- Thanos Ecosystem → Object Storage: stores data (evidence: `README.md`)
- Thanos Ecosystem → Alertmanager: sends alerts (evidence: `README.md`)
- Web Browser → Grafana: accesses (evidence: `README.md`)
- Grafana → RBAC Query Proxy: queries via (evidence: `README.md`)
- RBAC Query Proxy → Observatorium API: proxies queries (evidence: `README.md`)
- RBAC Query Proxy → Cluster Informer: uses cluster data (evidence: `proxy/pkg/proxy/proxy.go`)
- RBAC Query Proxy → Query Modifier: modifies queries (evidence: `proxy/pkg/proxy/proxy.go`)
- Dashboard Loader → Grafana: updates dashboards (evidence: `loaders/dashboards/pkg/controller/dashboard_controller.go`)
- MCO Operator → Rightsizing Analytics: registers controller
- MCO Operator → Operator Status: registers controller
- Endpoint Operator → Endpoint Status: reports conditions (evidence: `operators/endpointmetrics/controllers/observabilityendpoint/observabilityaddon_controller.go`)
