# project-koku/koku-metrics-operator architecture

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

- Interactive diagram: https://gitdiagram.com/project-koku/koku-metrics-operator
- Repository: https://github.com/project-koku/koku-metrics-operator

## Overview

Koku Metrics Operator watches a CostManagementMetricsConfig resource, configures collection from cluster monitoring, gathers OpenShift usage, produces report files, packages them, and uploads them to Koku. It can also register the cluster as a Sources API source and manage persistent storage for its deployment. The controller is the principal workflow owner; sampled excerpts and the source index support its calls into collection, packaging, HTTP, Sources, and storage. Some internal details are unsampled, so uncertain links are omitted.

Main entry points: [`internal/controller/costmanagementmetricsconfig_controller.go`](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/costmanagementmetricsconfig_controller.go) (Config reconciler), [`internal/collector/collector.go`](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/collector.go) (Usage reports), [`internal/crhchttp/http_cloud_dot_redhat.go`](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/crhchttp/http_cloud_dot_redhat.go) (Koku upload client), [`internal/controller/prometheus.go`](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/prometheus.go) (Prometheus control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator control"]
  node_main["Manager startup<br/>[main.go]"]
  node_controller["Config reconciler"]
  node_cr["Metrics config"]
end

subgraph group_collection["Usage collection"]
  node_promcontrol["Prometheus control<br/>[prometheus.go]"]
  node_collector["Usage reports<br/>[collector.go]"]
  node_promcollector["Prometheus client<br/>[prometheus.go]"]
  node_queries["Metric queries<br/>[queries.go]"]
  node_report["Report formatting<br/>[report.go]"]
end

subgraph group_delivery["Report delivery"]
  node_directories["Report directories<br/>[dirconfig.go]"]
  node_packaging["Archive packaging<br/>[packaging.go]"]
  node_upload["Koku upload client"]
  node_sources["Source registration<br/>[handler.go]"]
  node_auth["Upload authentication<br/>[config.go]"]
end

subgraph group_cluster["Cluster integration"]
  node_storage["PVC management<br/>[storage.go]"]
  node_clusterver["Cluster version<br/>[cv.go]"]
end

node_admin(("Cluster admin"))
node_prometheus[("Cluster Prometheus")]
node_koku(("Koku service"))

node_admin -.->|"configures"| node_cr
node_main -->|"starts"| node_controller
node_controller -->|"reconciles"| node_cr
node_controller -.->|"coordinates"| node_promcontrol
node_controller -->|"collects"| node_collector
node_controller -->|"packages"| node_packaging
node_controller -->|"uploads"| node_upload
node_controller -->|"registers source"| node_sources
node_controller -->|"manages"| node_storage
node_controller -->|"checks version"| node_clusterver
node_promcontrol -.->|"configures"| node_promcollector
node_promcollector -.->|"queries"| node_prometheus
node_collector -->|"writes reports"| node_directories
node_collector -.->|"uses query definitions"| node_queries
node_collector -.->|"formats output"| node_report
node_packaging -->|"reads files"| node_directories
node_upload -.->|"sends archive"| node_koku
node_sources -->|"uses HTTP client"| node_upload
node_upload -.->|"uses auth config"| node_auth
node_auth -.->|"requests token"| node_koku

click node_main "https://github.com/project-koku/koku-metrics-operator/blob/main/cmd/main.go"
click node_controller "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/costmanagementmetricsconfig_controller.go"
click node_cr "https://github.com/project-koku/koku-metrics-operator/blob/main/api/v1beta1/metricsconfig_types.go"
click node_promcontrol "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/prometheus.go"
click node_collector "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/collector.go"
click node_promcollector "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/prometheus.go"
click node_queries "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/queries.go"
click node_report "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/report.go"
click node_directories "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/dirconfig/dirconfig.go"
click node_packaging "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/packaging/packaging.go"
click node_upload "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/crhchttp/http_cloud_dot_redhat.go"
click node_sources "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/sources/handler.go"
click node_storage "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/storage/storage.go"
click node_clusterver "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/clusterversion/cv.go"
click node_auth "https://github.com/project-koku/koku-metrics-operator/blob/main/internal/crhchttp/config.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_main,node_controller,node_cr toneBlue
class node_promcontrol,node_collector,node_promcollector,node_queries,node_report,node_prometheus toneAmber
class node_directories,node_packaging,node_upload,node_sources,node_auth toneMint
class node_storage,node_clusterver toneRose
class node_admin,node_koku toneIndigo
```

## Components

### Operator control

- [Manager startup](https://github.com/project-koku/koku-metrics-operator/blob/main/cmd/main.go): `cmd/main.go`
- [Config reconciler](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/costmanagementmetricsconfig_controller.go): `internal/controller/costmanagementmetricsconfig_controller.go`
- [Metrics config](https://github.com/project-koku/koku-metrics-operator/blob/main/api/v1beta1/metricsconfig_types.go): `api/v1beta1/metricsconfig_types.go`

### Usage collection

- [Prometheus control](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/controller/prometheus.go): `internal/controller/prometheus.go`
- [Usage reports](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/collector.go): `internal/collector/collector.go`
- [Prometheus client](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/prometheus.go): `internal/collector/prometheus.go`
- [Metric queries](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/queries.go): `internal/collector/queries.go`
- [Report formatting](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/collector/report.go): `internal/collector/report.go`

### Report delivery

- [Report directories](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/dirconfig/dirconfig.go): `internal/dirconfig/dirconfig.go`
- [Archive packaging](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/packaging/packaging.go): `internal/packaging/packaging.go`
- [Koku upload client](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/crhchttp/http_cloud_dot_redhat.go): `internal/crhchttp/http_cloud_dot_redhat.go`
- [Source registration](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/sources/handler.go): `internal/sources/handler.go`
- [Upload authentication](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/crhchttp/config.go): `internal/crhchttp/config.go`

### Cluster integration

- [PVC management](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Cluster version](https://github.com/project-koku/koku-metrics-operator/blob/main/internal/clusterversion/cv.go): `internal/clusterversion/cv.go`

### Other components

- **Cluster admin**
- **Cluster Prometheus**
- **Koku service**

## Connections

- Cluster admin → Metrics config: configures (evidence: `README.md`)
- Manager startup → Config reconciler: starts (evidence: `cmd/main.go`)
- Config reconciler → Metrics config: reconciles (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → Prometheus control: coordinates
- Config reconciler → Usage reports: collects (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → Archive packaging: packages (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → Koku upload client: uploads (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → Source registration: registers source (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → PVC management: manages (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Config reconciler → Cluster version: checks version (evidence: `internal/controller/costmanagementmetricsconfig_controller.go`)
- Prometheus control → Prometheus client: configures
- Prometheus client → Cluster Prometheus: queries
- Usage reports → Report directories: writes reports (evidence: `internal/collector/collector.go`)
- Usage reports → Metric queries: uses query definitions
- Usage reports → Report formatting: formats output
- Archive packaging → Report directories: reads files (evidence: `internal/packaging/packaging.go`)
- Koku upload client → Koku service: sends archive (evidence: `README.md`)
- Source registration → Koku upload client: uses HTTP client (evidence: `internal/sources/handler.go`)
- Koku upload client → Upload authentication: uses auth config
- Upload authentication → Koku service: requests token
