Skip to content

Quickstart: Kind

This guide walks you through deploying a DocumentDB cluster on a local Kind (Kubernetes in Docker) cluster. Kind is ideal for development, testing, and CI pipelines.

Prerequisites

Tool Version Purpose
Docker 20.10+ Container runtime for Kind
Kind v0.31+ Local Kubernetes cluster
kubectl 1.35+ Kubernetes CLI
Helm 3.x Package manager
mongosh Latest MongoDB shell for connecting

Important

The DocumentDB operator requires Kubernetes 1.35+ for ImageVolume GA support. Kind v0.31+ ships images for Kubernetes 1.35.

Create a Kind Kubernetes cluster

kind create cluster --name documentdb-dev --image kindest/node:v1.35.0

Verify the Kubernetes cluster is running:

kubectl cluster-info
kubectl get nodes

NAME                           STATUS   ROLES           AGE   VERSION
documentdb-dev-control-plane   Ready    control-plane   30s   v1.35.0

Install cert-manager

The operator uses cert-manager to manage TLS certificates.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true \
  --wait

Verify that cert-manager is running:

kubectl get pods -n cert-manager

All three pods (cert-manager, cert-manager-cainjector, cert-manager-webhook) should show Running.

Install the DocumentDB operator

The operator Helm chart automatically installs the CloudNativePG operator as a dependency.

helm repo add documentdb https://documentdb.github.io/documentdb-kubernetes-operator
helm repo update
helm install documentdb-operator documentdb/documentdb-operator \
  --namespace documentdb-operator \
  --create-namespace \
  --wait

Verify:

kubectl get deployment -n documentdb-operator

NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
documentdb-operator   1/1     1            1           60s

Deploy a DocumentDB cluster

Create credentials

Create namespace and credentials Secret
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: documentdb-ns
---
apiVersion: v1
kind: Secret
metadata:
  name: documentdb-credentials
  namespace: documentdb-ns
type: Opaque
stringData:
  username: dev_user
  password: DevPassword123
EOF

Tip

The operator expects a Secret with username and password keys. The default Secret name is documentdb-credentials. To use a different name, set spec.documentDbCredentialSecret in your DocumentDB resource.

Create the DocumentDB cluster

Deploy a single-node DocumentDB cluster
cat <<EOF | kubectl apply -f -
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: documentdb-ns
spec:
  nodeCount: 1
  instancesPerNode: 1
  documentDbCredentialSecret: documentdb-credentials
  resource:
    storage:
      pvcSize: 10Gi
  exposeViaService:
    serviceType: ClusterIP
EOF

Wait for the DocumentDB cluster to become healthy:

kubectl get documentdb my-documentdb -n documentdb-ns -w

NAME            STATUS                     CONNECTION STRING
my-documentdb   Cluster in healthy state   mongodb://...

Verify all pods are running (each pod runs a PostgreSQL container and a DocumentDB Gateway sidecar):

kubectl get pods -n documentdb-ns

NAME              READY   STATUS    RESTARTS   AGE
my-documentdb-1   2/2     Running   0          2m

Connect to DocumentDB

Set up port forwarding to access the DocumentDB Gateway (port 10260):

kubectl port-forward pod/my-documentdb-1 10260:10260 -n documentdb-ns

In a new terminal, retrieve the connection string from the DocumentDB cluster status and connect:

# Get the connection string (contains embedded kubectl commands to resolve credentials)
kubectl get documentdb my-documentdb -n documentdb-ns -o jsonpath='{.status.connectionString}'

Use mongosh with the resolved credentials:

mongosh "mongodb://dev_user:DevPassword123@127.0.0.1:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true&replicaSet=rs0"

Tip

The CONNECTION STRING column in kubectl get documentdb output contains embedded kubectl commands that extract the username and password from the credentials Secret at runtime. You can copy and eval the full string, or substitute your known credentials directly as shown above.

Try inserting and querying data:

use testdb
db.users.insertOne({ name: "Alice", role: "admin" })
db.users.find()

For more connection options including application drivers in Python, Node.js, Go, and Java, see Connecting to DocumentDB.

Local high availability

To test high availability locally, deploy with multiple instances:

Deploy a 3-instance DocumentDB cluster for HA
cat <<EOF | kubectl apply -f -
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: documentdb-ns
spec:
  nodeCount: 1
  instancesPerNode: 3
  documentDbCredentialSecret: documentdb-credentials
  resource:
    storage:
      pvcSize: 10Gi
  exposeViaService:
    serviceType: ClusterIP
EOF

This creates one primary instance and two replicas with automatic failover.

kubectl get pods -n documentdb-ns

NAME              READY   STATUS    RESTARTS   AGE
my-documentdb-1   2/2     Running   0          3m
my-documentdb-2   2/2     Running   0          2m
my-documentdb-3   2/2     Running   0          1m

Development with a local registry

For operator development, you can create a Kind Kubernetes cluster with a local Docker registry. This allows you to build and push custom operator images without an external registry.

cd operator/src
DEPLOY=true DEPLOY_CLUSTER=true ./scripts/development/deploy.sh

This script:

  1. Creates a Kind Kubernetes cluster with a local registry (localhost:5001)
  2. Builds and pushes the operator and sidecar-injector images
  3. Installs cert-manager and the DocumentDB operator
  4. Optionally deploys a DocumentDB cluster

See the Development Environment Guide for more details.

Clean up

# Delete the DocumentDB cluster
kubectl delete documentdb my-documentdb -n documentdb-ns

# Uninstall the operator
helm uninstall documentdb-operator -n documentdb-operator

# Delete the Kind Kubernetes cluster
kind delete cluster --name documentdb-dev

Next steps