# ravendb/ravendb-operator architecture

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

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

## Overview

RavenDB Kubernetes Operator reconciles a RavenDBCluster custom resource into Kubernetes resources, then observes those resources and reports cluster health and status. Admission webhooks validate and default submitted configuration; reconciliation is coordinated by the director and resource-owning actors. The README also identifies TLS/certificate management, external access, persistent storage, bootstrapping, and safety-gated rolling upgrades as product capabilities. Some subsystem links are documented rather than visible in the sampled implementation; those are marked dashed or omitted where the caller is unclear.

Main entry points: [`internal/controller/ravendbcluster_controller.go`](https://github.com/ravendb/ravendb-operator/blob/main/internal/controller/ravendbcluster_controller.go) (Cluster Controller), [`pkg/actor`](https://github.com/ravendb/ravendb-operator/tree/main/pkg/actor) (Cluster Actors), [`pkg/director/director.go`](https://github.com/ravendb/ravendb-operator/blob/main/pkg/director/director.go) (Actor Director), [`api/v1/webhook.go`](https://github.com/ravendb/ravendb-operator/blob/main/api/v1/webhook.go) (Admission Hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Cluster API"]
  node_cluster_cr["RavenDBCluster CR<br/>[cluster_types.go]"]
end

subgraph group_reconcile["Reconciliation"]
  node_controller["Cluster Controller"]
  node_director["Actor Director<br/>[director.go]"]
  node_cluster_actors["Cluster Actors"]
  node_node_actors["Node Actors"]
  node_service_actor["Service Actor<br/>[service_actor.go]"]
  node_resource_builders["Kubernetes Builders"]
  node_statefulset_builder["StatefulSet Builder<br/>[statefulset.go]"]
  node_service_builder["Service Builder<br/>[service.go]"]
end

subgraph group_lifecycle["Cluster Lifecycle"]
  node_cluster_resources["Cluster Resources"]
  node_storage[("Persistent Storage<br/>[volume.go]")]
  node_bootstrap["Cluster Bootstrap"]
  node_hooks["Lifecycle Hooks<br/>[hooks_actor.go]"]
  node_external_access["External Access<br/>[ingress.go]"]
  node_upgrade["Upgrade Safety Gates"]
end

subgraph group_observe["Health And Status"]
  node_health_collector["Resource Collector"]
  node_health_evaluator["Health Evaluator<br/>[evaluator.go]"]
  node_status["Cluster Status<br/>[status_helpers.go]"]
end

subgraph group_admission["Admission"]
  node_webhook_entry["Admission Hooks<br/>[webhook.go]"]
  node_validators["Spec Validators"]
  node_mutator["Spec Defaults<br/>[mutator.go]"]
end

node_operator(("Operator"))
node_kubernetes[("Kubernetes API")]
node_ravendb(("RavenDB Nodes"))

node_operator -->|"submits spec"| node_cluster_cr
node_cluster_cr -.->|"admission request"| node_webhook_entry
node_webhook_entry -->|"registers validators"| node_validators
node_webhook_entry -->|"defaults spec"| node_mutator
node_operator -.->|"starts manager"| node_controller
node_controller -->|"reads resource"| node_cluster_cr
node_controller -->|"executes actors"| node_director
node_director -->|"dispatches cluster"| node_cluster_actors
node_director -->|"dispatches per node"| node_node_actors
node_node_actors -.->|"builds workload"| node_statefulset_builder
node_service_actor -->|"builds service"| node_service_builder
node_service_builder -->|"defines services"| node_cluster_resources
node_statefulset_builder -.->|"configures volumes"| node_storage
node_cluster_actors -.->|"applies resources"| node_cluster_resources
node_cluster_actors -.->|"creates bootstrap job"| node_bootstrap
node_cluster_actors -.->|"manages hooks"| node_hooks
node_cluster_actors -.->|"configures routing"| node_external_access
node_controller -->|"observes resources"| node_health_collector
node_health_collector -.->|"provides facts"| node_health_evaluator
node_health_evaluator -.->|"computes conditions"| node_status
node_controller -->|"patches status"| node_status
node_controller -.->|"coordinates upgrades"| node_upgrade
node_controller -.->|"applies and reads"| node_kubernetes
node_cluster_resources -.->|"creates objects"| node_kubernetes
node_ravendb -.->|"runs as resources"| node_kubernetes

click node_cluster_cr "https://github.com/ravendb/ravendb-operator/blob/main/api/v1/cluster_types.go"
click node_webhook_entry "https://github.com/ravendb/ravendb-operator/blob/main/api/v1/webhook.go"
click node_validators "https://github.com/ravendb/ravendb-operator/tree/main/pkg/webhook/validator"
click node_mutator "https://github.com/ravendb/ravendb-operator/blob/main/pkg/webhook/mutator/mutator.go"
click node_controller "https://github.com/ravendb/ravendb-operator/blob/main/internal/controller/ravendbcluster_controller.go"
click node_director "https://github.com/ravendb/ravendb-operator/blob/main/pkg/director/director.go"
click node_cluster_actors "https://github.com/ravendb/ravendb-operator/tree/main/pkg/actor"
click node_node_actors "https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/statefulset_actor.go"
click node_service_actor "https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/service_actor.go"
click node_resource_builders "https://github.com/ravendb/ravendb-operator/tree/main/pkg/resource"
click node_statefulset_builder "https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/statefulset.go"
click node_service_builder "https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/service.go"
click node_cluster_resources "https://github.com/ravendb/ravendb-operator/tree/main/pkg/resource"
click node_storage "https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/volume.go"
click node_bootstrap "https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/bootstrapper_actor.go"
click node_hooks "https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/hooks_actor.go"
click node_external_access "https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/ingress.go"
click node_upgrade "https://github.com/ravendb/ravendb-operator/tree/main/pkg/upgrade"
click node_health_collector "https://github.com/ravendb/ravendb-operator/blob/main/pkg/health/resource_collector.go"
click node_health_evaluator "https://github.com/ravendb/ravendb-operator/blob/main/pkg/health/evaluator.go"
click node_status "https://github.com/ravendb/ravendb-operator/blob/main/api/v1/status_helpers.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_cluster_cr toneBlue
class node_controller,node_director,node_cluster_actors,node_node_actors,node_service_actor,node_resource_builders,node_statefulset_builder,node_service_builder,node_kubernetes toneAmber
class node_cluster_resources,node_storage,node_bootstrap,node_hooks,node_external_access,node_upgrade toneMint
class node_health_collector,node_health_evaluator,node_status toneRose
class node_webhook_entry,node_validators,node_mutator,node_operator,node_ravendb toneIndigo
```

## Components

### Cluster API

- [RavenDBCluster CR](https://github.com/ravendb/ravendb-operator/blob/main/api/v1/cluster_types.go): `api/v1/cluster_types.go`

### Reconciliation

- [Cluster Controller](https://github.com/ravendb/ravendb-operator/blob/main/internal/controller/ravendbcluster_controller.go): `internal/controller/ravendbcluster_controller.go`
- [Actor Director](https://github.com/ravendb/ravendb-operator/blob/main/pkg/director/director.go): `pkg/director/director.go`
- [Cluster Actors](https://github.com/ravendb/ravendb-operator/tree/main/pkg/actor): `pkg/actor`
- [Node Actors](https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/statefulset_actor.go): `pkg/actor/statefulset_actor.go`
- [Service Actor](https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/service_actor.go): `pkg/actor/service_actor.go`
- [Kubernetes Builders](https://github.com/ravendb/ravendb-operator/tree/main/pkg/resource): `pkg/resource`
- [StatefulSet Builder](https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/statefulset.go): `pkg/resource/statefulset.go`
- [Service Builder](https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/service.go): `pkg/resource/service.go`

### Cluster Lifecycle

- [Cluster Resources](https://github.com/ravendb/ravendb-operator/tree/main/pkg/resource): `pkg/resource`
- [Persistent Storage](https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/volume.go): `pkg/resource/volume.go`
- [Cluster Bootstrap](https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/bootstrapper_actor.go): `pkg/actor/bootstrapper_actor.go`
- [Lifecycle Hooks](https://github.com/ravendb/ravendb-operator/blob/main/pkg/actor/hooks_actor.go): `pkg/actor/hooks_actor.go`
- [External Access](https://github.com/ravendb/ravendb-operator/blob/main/pkg/resource/ingress.go): `pkg/resource/ingress.go`
- [Upgrade Safety Gates](https://github.com/ravendb/ravendb-operator/tree/main/pkg/upgrade): `pkg/upgrade`

### Health And Status

- [Resource Collector](https://github.com/ravendb/ravendb-operator/blob/main/pkg/health/resource_collector.go): `pkg/health/resource_collector.go`
- [Health Evaluator](https://github.com/ravendb/ravendb-operator/blob/main/pkg/health/evaluator.go): `pkg/health/evaluator.go`
- [Cluster Status](https://github.com/ravendb/ravendb-operator/blob/main/api/v1/status_helpers.go): `api/v1/status_helpers.go`

### Admission

- [Admission Hooks](https://github.com/ravendb/ravendb-operator/blob/main/api/v1/webhook.go): `api/v1/webhook.go`
- [Spec Validators](https://github.com/ravendb/ravendb-operator/tree/main/pkg/webhook/validator): `pkg/webhook/validator`
- [Spec Defaults](https://github.com/ravendb/ravendb-operator/blob/main/pkg/webhook/mutator/mutator.go): `pkg/webhook/mutator/mutator.go`

### Other components

- **Operator**
- **Kubernetes API**
- **RavenDB Nodes**

## Connections

- Operator → RavenDBCluster CR: submits spec (evidence: `README.md`)
- RavenDBCluster CR → Admission Hooks: admission request (evidence: `README.md`)
- Admission Hooks → Spec Validators: registers validators (evidence: `api/v1/webhook.go`)
- Admission Hooks → Spec Defaults: defaults spec (evidence: `api/v1/webhook.go`)
- Operator → Cluster Controller: starts manager
- Cluster Controller → RavenDBCluster CR: reads resource (evidence: `internal/controller/ravendbcluster_controller.go`)
- Cluster Controller → Actor Director: executes actors (evidence: `internal/controller/ravendbcluster_controller.go`)
- Actor Director → Cluster Actors: dispatches cluster (evidence: `pkg/director/director.go`)
- Actor Director → Node Actors: dispatches per node (evidence: `pkg/director/director.go`)
- Node Actors → StatefulSet Builder: builds workload
- Service Actor → Service Builder: builds service (evidence: `pkg/actor/service_actor.go`)
- Service Builder → Cluster Resources: defines services (evidence: `pkg/resource/service.go`)
- StatefulSet Builder → Persistent Storage: configures volumes
- Cluster Actors → Cluster Resources: applies resources
- Cluster Actors → Cluster Bootstrap: creates bootstrap job
- Cluster Actors → Lifecycle Hooks: manages hooks
- Cluster Actors → External Access: configures routing
- Cluster Controller → Resource Collector: observes resources (evidence: `internal/controller/ravendbcluster_controller.go`)
- Resource Collector → Health Evaluator: provides facts
- Health Evaluator → Cluster Status: computes conditions
- Cluster Controller → Cluster Status: patches status (evidence: `internal/controller/ravendbcluster_controller.go`)
- Cluster Controller → Upgrade Safety Gates: coordinates upgrades
- Cluster Controller → Kubernetes API: applies and reads
- Cluster Resources → Kubernetes API: creates objects
- RavenDB Nodes → Kubernetes API: runs as resources
