# mongodb/mongodb-kubernetes-operator architecture

> Architecture diagram of the GitHub repository mongodb/mongodb-kubernetes-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/mongodb/mongodb-kubernetes-operator
- Repository: https://github.com/mongodb/mongodb-kubernetes-operator

## Overview

This is the MongoDB Community Kubernetes Operator. A cluster user declares a MongoDBCommunity resource; the operator reconciles it into Kubernetes workloads and services, while coordinating replica-set configuration and reporting status. Documented capabilities include version changes and scaling, SCRAM users and custom roles, TLS, and Prometheus metrics. The graph uses sampled controller and workload-construction references for internal links; README-only feature links are identified by their evidence path.

Main entry points: [`controllers/replica_set_controller.go`](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/replica_set_controller.go) (Replica-set reconciler), [`controllers/construct/mongodbstatefulset.go`](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/construct/mongodbstatefulset.go) (StatefulSet construction), [`pkg/authentication/authentication.go`](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/authentication.go) (Authentication dispatch), [`controllers/prometheus.go`](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/prometheus.go) (Prometheus metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control plane"]
  node_mongodbcommunity["MongoDBCommunity resource"]
  node_manager["Operator manager<br/>[main.go]"]
  node_reconciler["Replica-set reconciler"]
  node_validation["Spec validation<br/>[validation.go]"]
  node_status["Status reporting"]
  node_cleanup["Resource cleanup<br/>[mongodb_cleanup.go]"]
end

subgraph group_workload["MongoDB workloads"]
  node_workloadbuilder["StatefulSet construction"]
  node_kubernetes[("Kubernetes API")]
  node_replicaset["MongoDB replica set"]
  node_versionhook["Version-change hook<br/>[main.go]"]
end

subgraph group_security["Security and identity"]
  node_auth["Authentication dispatch<br/>[authentication.go]"]
  node_scram["SCRAM authentication<br/>[scram.go]"]
  node_x509["X.509 authentication<br/>[x509.go]"]
  node_tls["TLS management<br/>[mongodb_tls.go]"]
  node_users["Database users<br/>[mongodb_users.go]"]
end

subgraph group_runtime["Runtime support"]
  node_readiness["Readiness probe<br/>[main.go]"]
  node_automation["Automation configuration"]
  node_agent["MongoDB agent"]
  node_prometheus["Prometheus metrics<br/>[prometheus.go]"]
end

node_user(("Cluster user"))

node_user -->|"declares"| node_mongodbcommunity
node_manager -->|"starts reconciliation"| node_reconciler
node_reconciler -->|"reads and reconciles"| node_mongodbcommunity
node_reconciler -->|"validates spec"| node_validation
node_reconciler -->|"builds workloads"| node_workloadbuilder
node_workloadbuilder -->|"configures agent"| node_automation
node_reconciler -->|"creates resources"| node_kubernetes
node_reconciler -->|"deploys and scales"| node_replicaset
node_reconciler -->|"updates status"| node_status
node_reconciler -.->|"cleans resources"| node_cleanup
node_replicaset -->|"runs during upgrades"| node_versionhook
node_workloadbuilder -->|"adds probe"| node_readiness
node_replicaset -.->|"reports readiness"| node_readiness
node_reconciler -->|"coordinates agent"| node_agent
node_reconciler -->|"configures authentication"| node_auth
node_auth -->|"enables SCRAM"| node_scram
node_auth -->|"enables X.509"| node_x509
node_reconciler -->|"reconciles TLS"| node_tls
node_replicaset -->|"uses TLS connections"| node_tls
node_reconciler -->|"manages users"| node_users
node_replicaset -->|"authenticates users"| node_users
node_reconciler -->|"configures metrics"| node_prometheus
node_prometheus -->|"exposes metrics"| node_replicaset
node_reconciler -->|"generates configuration"| node_automation

click node_mongodbcommunity "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/api/v1/mongodbcommunity_types.go"
click node_manager "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/manager/main.go"
click node_reconciler "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/replica_set_controller.go"
click node_validation "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/validation/validation.go"
click node_status "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_status_options.go"
click node_cleanup "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_cleanup.go"
click node_workloadbuilder "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/construct/mongodbstatefulset.go"
click node_versionhook "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/versionhook/main.go"
click node_readiness "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/readiness/main.go"
click node_automation "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/automationconfig/automation_config.go"
click node_agent "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/agent/replica_set_port_manager.go"
click node_auth "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/authentication.go"
click node_scram "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/scram/scram.go"
click node_x509 "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/x509/x509.go"
click node_tls "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_tls.go"
click node_users "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_users.go"
click node_prometheus "https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/prometheus.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_mongodbcommunity,node_manager,node_reconciler,node_validation,node_status,node_cleanup,node_user toneBlue
class node_workloadbuilder,node_kubernetes,node_replicaset,node_versionhook toneAmber
class node_auth,node_scram,node_x509,node_tls,node_users toneMint
class node_readiness,node_automation,node_agent,node_prometheus toneRose
```

## Components

### Operator control plane

- [MongoDBCommunity resource](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/api/v1/mongodbcommunity_types.go): `api/v1/mongodbcommunity_types.go`
- [Operator manager](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/manager/main.go): `cmd/manager/main.go`
- [Replica-set reconciler](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/replica_set_controller.go): `controllers/replica_set_controller.go`
- [Spec validation](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/validation/validation.go): `controllers/validation/validation.go`
- [Status reporting](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_status_options.go): `controllers/mongodb_status_options.go`
- [Resource cleanup](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_cleanup.go): `controllers/mongodb_cleanup.go`

### MongoDB workloads

- [StatefulSet construction](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/construct/mongodbstatefulset.go): `controllers/construct/mongodbstatefulset.go`
- **Kubernetes API**
- **MongoDB replica set**
- [Version-change hook](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/versionhook/main.go): `cmd/versionhook/main.go`

### Security and identity

- [Authentication dispatch](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/authentication.go): `pkg/authentication/authentication.go`
- [SCRAM authentication](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/scram/scram.go): `pkg/authentication/scram/scram.go`
- [X.509 authentication](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/authentication/x509/x509.go): `pkg/authentication/x509/x509.go`
- [TLS management](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_tls.go): `controllers/mongodb_tls.go`
- [Database users](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/mongodb_users.go): `controllers/mongodb_users.go`

### Runtime support

- [Readiness probe](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/cmd/readiness/main.go): `cmd/readiness/main.go`
- [Automation configuration](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/automationconfig/automation_config.go): `pkg/automationconfig/automation_config.go`
- [MongoDB agent](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/pkg/agent/replica_set_port_manager.go): `pkg/agent/replica_set_port_manager.go`
- [Prometheus metrics](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/controllers/prometheus.go): `controllers/prometheus.go`

### Other components

- **Cluster user**

## Connections

- Cluster user → MongoDBCommunity resource: declares (evidence: `README.md`)
- Operator manager → Replica-set reconciler: starts reconciliation (evidence: `cmd/manager/main.go`)
- Replica-set reconciler → MongoDBCommunity resource: reads and reconciles (evidence: `controllers/replica_set_controller.go`)
- Replica-set reconciler → Spec validation: validates spec (evidence: `controllers/replica_set_controller.go`)
- Replica-set reconciler → StatefulSet construction: builds workloads (evidence: `controllers/replica_set_controller.go`)
- StatefulSet construction → Automation configuration: configures agent (evidence: `controllers/construct/mongodbstatefulset.go`)
- Replica-set reconciler → Kubernetes API: creates resources (evidence: `controllers/replica_set_controller.go`)
- Replica-set reconciler → MongoDB replica set: deploys and scales (evidence: `README.md`)
- Replica-set reconciler → Status reporting: updates status (evidence: `controllers/replica_set_controller.go`)
- Replica-set reconciler → Resource cleanup: cleans resources
- MongoDB replica set → Version-change hook: runs during upgrades (evidence: `README.md`)
- StatefulSet construction → Readiness probe: adds probe (evidence: `controllers/construct/mongodbstatefulset.go`)
- MongoDB replica set → Readiness probe: reports readiness
- Replica-set reconciler → MongoDB agent: coordinates agent (evidence: `controllers/replica_set_controller.go`)
- Replica-set reconciler → Authentication dispatch: configures authentication (evidence: `controllers/replica_set_controller.go`)
- Authentication dispatch → SCRAM authentication: enables SCRAM (evidence: `pkg/authentication/authentication.go`)
- Authentication dispatch → X.509 authentication: enables X.509 (evidence: `pkg/authentication/authentication.go`)
- Replica-set reconciler → TLS management: reconciles TLS (evidence: `controllers/replica_set_controller.go`)
- MongoDB replica set → TLS management: uses TLS connections (evidence: `README.md`)
- Replica-set reconciler → Database users: manages users (evidence: `README.md`)
- MongoDB replica set → Database users: authenticates users (evidence: `README.md`)
- Replica-set reconciler → Prometheus metrics: configures metrics (evidence: `controllers/replica_set_controller.go`)
- Prometheus metrics → MongoDB replica set: exposes metrics (evidence: `README.md`)
- Replica-set reconciler → Automation configuration: generates configuration (evidence: `controllers/replica_set_controller.go`)
