Skip to content

ravendb/ravendb-operator

BranchesTags

Repository files navigation

RavenDB Kubernetes Operator

The RavenDB Kubernetes Operator provides a fully automated way to deploy and manage secure RavenDB clusters on Kubernetes. It handles certificate management, bootstrapping, rolling upgrades with safety gates, external access, persistent storage orchestration, node lifecycle management, and continuous health and status evaluation - all driven from a single RavenDBCluster custom resource. The operator ensures that every component stays aligned with the declared spec, enabling fully reproducible, declarative RavenDB deployments.

Table of Contents

Prerequisites

Before installing the RavenDB Kubernetes Operator, ensure your environment meets the following requirements:

Installation

There are three supported installation methods:

  1. Helm (recommended) - install via the two official charts published on ArtifactHub.
  2. make deploy - local development / testing from source.
  3. OLM bundle - for clusters running Operator Lifecycle Manager.

The operator runs in a dedicated namespace (e.g. ravendb-operator-system); each RavenDBCluster and its Secrets live in their own workload namespace. The operator creates namespace-scoped ServiceAccount, Role, and RoleBinding resources per cluster namespace, scoped to only the operations the operator needs.

1. Install via Helm (recommended)

The Helm distribution is split into two charts, each owning a clearly-bounded lifecycle:

Chart Scope Installed Contains
ravendb-operator Cluster-wide Once per Kubernetes cluster Controller Deployment, RavenDBCluster CRD, RBAC, admission webhooks, cert-manager Certificate/Issuer
ravendb-cluster Per-namespace Once per RavenDB cluster you want to run A RavenDBCluster CR, its license/cert Secrets (provisioned or referenced), and Traefik IngressRouteTCPs when applicable

Install in that order: the operator first, then one cluster chart per RavenDB cluster.

Step 1 - install the operator

helm repo add ravendb-operator https://ravendb.github.io/ravendb-operator/helm
helm repo update

helm install ravendb-operator ravendb-operator/ravendb-operator \
  -n ravendb-operator-system --create-namespace

This installs the controller, CRDs, RBAC, and webhooks. The operator chart does not create cluster-side Secrets or RavenDBCluster resources. See helm/chart/README.md for full documentation, including the migration guide for users upgrading from operator chart 1.x to 2.0.0 (the legacy provisioning.* flow has been removed).

Step 2 - install a RavenDB cluster

helm install my-cluster ravendb-operator/ravendb-cluster \
  -n ravendb --create-namespace \
  -f my-values.yaml \
  --set-file secrets.license.file=/path/to/license.json \
  --set-file secrets.clientCert.file=/path/to/admin-client-cert.pfx \
  --set-file secrets.nodeCerts.files.a=/path/to/node-a/server.pfx \
  --set-file secrets.nodeCerts.files.b=/path/to/node-b/server.pfx \
  --set-file secrets.nodeCerts.files.c=/path/to/node-c/server.pfx

my-values.yaml mirrors RavenDBClusterSpec 1:1 (nodes, mode, domain, external access, storage, …). The chart provisions Secrets from --set-file arguments, or references pre-existing Secrets you create with kubectl if you'd rather manage them yourself (cert-manager, Vault, sealed-secrets, etc.).

For full options - provisioning vs BYO Secrets, Traefik routing, supported networking modes, upgrade and uninstall semantics, limitations - see helm/cluster-chart/README.md.

2. make deploy (development / local testing)

This installation method is intended only for local development, contributing to the operator, or testing changes before building a production image.
It uses the manifests generated by Kubebuilder under the config/ directory and deploys the operator directly from your local source tree.

git clone https://github.com/ravendb/ravendb-operator.git
cd ravendb-operator
# Option A: If you're modifying code or testing custom logic, build the operator binary.
# This compiles the controller and ensures your local environment is correct before deploying.
make build

#Option B: If you want to test the operator inside your own cluster (kind, minikube, or remote):
make docker-build IMG=<your-registry>/<repo>:<tag>
make docker-push IMG=<your-registry>/<repo>:<tag> # or load it inside your cluster

# Uninstall (clean up)
make undeploy

3. OLM bundle installation

# Install Operator Lifecycle Manager (OLM), a tool to help manage the Operators running on your cluster.
$ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.38.0/install.sh | bash -s v0.38.0

# Install the operator by running the following command
$ kubectl create -f https://operatorhub.io/install/ravendb-operator.yaml

# After install, watch the operator come up using next command
$ kubectl get csv -n operators

Custom Resource (RavenDBCluster)

The RavenDBCluster custom resource is the single source of truth for your RavenDB deployment.
It defines node topology, TLS mode (Let's Encrypt or self-signed), external access strategy (Ingress / LoadBalancer), storage layout, images, and bootstrap behavior.
Once the operator reconciles this resource, it will create and manage all underlying Kubernetes objects (StatefulSets, Services, Ingresses, Jobs, PVCs, etc.) needed to run the cluster.

Note: Feel free to shape the CRD however you need - the validation webhooks have your back, watching for misconfigurations and letting you know right away if something doesn’t look right.

For a deeper dive into each aspect of the spec, see the dedicated examples and documentation:

Below is an example of a Let's Encrypt–based cluster using the AWS-NLB external access mode and Perssist/Restoring Data.

apiVersion: ravendb.ravendb.io/v1
kind: RavenDBCluster
metadata:
  labels:
    app.kubernetes.io/name: ravendb-operator
  name: ravendbcluster-sample
  namespace: ravendb-dev
spec:
  nodes:
    - tag: a
      publicServerUrl: https://a.domain.development.run:443
      publicServerUrlTcp: tcp://a-tcp.domain.development.run:443
      certSecretRef: ravendb-certs-a
    - tag: b
      publicServerUrl: https://b.domain.development.run:443
      publicServerUrlTcp: tcp://b-tcp.domain.development.run:443
      certSecretRef: ravendb-certs-b
    - tag: c
      publicServerUrl: https://c.domain.development.run:443
      publicServerUrlTcp: tcp://c-tcp.domain.development.run:443
      certSecretRef: ravendb-certs-c
  image: ravendb/ravendb:latest
  imagePullPolicy: IfNotPresent
  mode: LetsEncrypt
  email: user@ravendb.net
  licenseSecretRef: ravendb-license
  clientCertSecretRef: ravendb-client-cert
  domain: domain.development.run
  env:
    RAVEN_Features_Availability: "Experimental"
  externalAccessConfiguration:
    type: aws-nlb
    awsExternalAccessContext:
      nodeMappings:
        - tag: a
          eipAllocationId: eipalloc-0f12ab34cd56ef789
          subnetId: subnet-0aa1bb22cc33dd44e
          availabilityZone: us-east-1a
        - tag: b
          eipAllocationId: eipalloc-0123abcd4567ef890
          subnetId: subnet-0555aa66bb77cc88d
          availabilityZone: us-east-1b
        - tag: c
          eipAllocationId: eipalloc-0abc1234def567890
          subnetId: subnet-0999ee11ff22gg33h
          availabilityZone: us-east-1c
  storage:
    data:
      size: 10Gi
      storageClassName: gp3
      accessModes:
        - ReadWriteOnce
    logs:
      ravendb:
        size: 1Gi
        storageClassName: gp2
        accessModes:
          - ReadWriteOnce
      audit:
        size: 1Gi
        storageClassName: gp2
    additionalVolumes:
        - name: scripts
            mountPath: /tmp/scripts
            volumeSource:
            configMap:
                name: myscripts
        - name: restore-volume
            mountPath: /tmp/restore
            volumeSource:
            persistentVolumeClaim:
                claimName: restore-backup-pvc

Features

Certificate and TLS Management

  • Let's Encrypt mode using RavenDB’s built-in LE support
  • Self-signed / bring-your-own certificate mode
  • Works with:
    • Per-node certificates from a RavenDB Setup Package.
    • A single shared server certificate in self-signed scenarios.
  • Manages webhook serving certificates through cert-manager.
  • Handles certificate provisioning for nodes and clients.
  • Automatically rotated secrets upon server-certificate renewal

Cluster Bootstrapper

  • Runs a short-lived Kubernetes Job to:
    • Wait for all RavenDB pods to be running.
    • Validate HTTPS reachability on all nodes.
    • Register the ClusterAdmin client certificate on the leader node.
    • Form the cluster (leader + members/watchers) based on spec.nodes.
  • Declarative definition of node topology, URLs, and certificate references.

External Access Management

  • Supports multiple exposure mechanisms:
    • AWS Network Load Balancer (one NLB per node, with explicit tag → EIP/subnet/AZ mapping).
    • Azure Load Balancer (per-node public IPs via AKS-managed SLB frontends).
    • NGINX Ingress.
    • HAProxy Ingress.
    • Traefik Ingress.

Storage Configuration

  • Declarative configuration of data, log, and audit volumes.
  • Supports Kubernetes storage backends including:
    • local-path
    • AWS EBS / EBS-CSI
    • Azure Disk / Azure Disk CSI
    • Additional volumes (ConfigMap, Secret, PVC, emptyDir)

Environment Options

  • Ability to set environment variables on RavenDB pods via spec.env (for feature flags and advanced configuration).

Rolling Upgrades

  • Orchestrates rolling upgrades of RavenDB nodes.
  • Ensures availability and ordering requirements during updates.
  • Performs node-by-node upgrades in the order defined in the RavenDBCluster spec.
  • Stops the upgrade on failed gates, keeps the state visible in status and Events, and automatically resumes from the same node once the underlying issue is fixed.
  • Prevents accidental version downgrades.

Health and Status Reporting

  • Exposes a single lifecycle field, .status.phase (Deploying, Running, Error), plus a short .status.message explaining the current state.
  • Maintains detailed .status.conditions[] for Ready, Progressing, Degraded, and required health gates such as CertificatesReady, LicensesValid, StorageReady, NodesHealthy, BootstrapCompleted, and ExternalAccessReady.
  • Derives phase deterministically from these conditions and emits Kubernetes Events on every condition transition, so kubectl describe ravendbclusters <name> shows exactly what is blocking readiness and why.

Development and Testing Support

  • Local deployment via make deploy without requiring Helm or OLM.
  • Validating and mutating admission webhooks for CRD correctness.
  • Server-side apply for consistent updates and ownership.
  • Supports incremental and partial reconciliations based on resource changes.

About

The official RavenDB Kubernetes Operator

Topics

go kubernetes k8s cloud-native operator-framework

Resources

Readme

License

View license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

8 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases 3

v2.0.0 Latest
Jun 16, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages