Skip to content

TLS Configuration

Overview

TLS encrypts connections between your applications and DocumentDB. Configure it to protect data in transit and meet your security requirements.

The DocumentDB gateway always encrypts connections — TLS is active regardless of the mode you choose. The spec.tls.gateway.mode field controls how the operator manages TLS certificates:

apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
spec:
  tls:
    gateway:
      mode: SelfSigned   # Disabled | SelfSigned | CertManager | Provided

For the full field reference, see TLSConfiguration in the API Reference.

Configuration

Select your TLS mode below. Each tab shows prerequisites, the complete YAML configuration, and connection instructions.

Best for: Development and testing only

Not recommended for production

Prerequisites: None

Disabled mode means the operator does not manage TLS certificates. However, the gateway still encrypts all connections using an internally generated self-signed certificate. Clients must connect with tls=true&tlsAllowInvalidCertificates=true.

documentdb-tls-disabled.yaml
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: default
spec:
  nodeCount: 1
  instancesPerNode: 1
  resource:
    storage:
      pvcSize: 10Gi
  exposeViaService:
    serviceType: ClusterIP
  tls:
    gateway:
      mode: Disabled

Connect with mongosh:

mongosh "mongodb://<username>:<password>@<host>:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true"

Best for: Development, testing, and environments without external PKI (Public Key Infrastructure)

Prerequisites

cert-manager must be installed in the Kubernetes cluster. See Install cert-manager for setup instructions.

SelfSigned mode uses cert-manager to automatically generate, manage, and rotate a self-signed server certificate (90-day validity, renewed 15 days before expiry). No additional configuration is needed beyond setting the mode.

documentdb-tls-selfsigned.yaml
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: default
spec:
  nodeCount: 1
  instancesPerNode: 3
  resource:
    storage:
      pvcSize: 10Gi
  exposeViaService:
    serviceType: ClusterIP
  tls:
    gateway:
      mode: SelfSigned

Connect with mongosh:

# Extract the CA certificate from the Secret
kubectl get secret my-documentdb-gateway-cert-tls -n default \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

# Connect with TLS
mongosh "mongodb://<username>:<password>@<host>:10260/?directConnection=true&authMechanism=SCRAM-SHA-256" \
  --tls --tlsCAFile ca.crt

Best for: Production with existing cert-manager infrastructure

Prerequisites

cert-manager must be installed (see Install cert-manager), plus a configured Issuer or ClusterIssuer.

Setting up a CA Issuer with cert-manager

If you don't already have an Issuer, you can bootstrap a simple CA Issuer:

cert-manager-ca-issuer.yaml
# Step 1: A self-signed issuer to bootstrap the CA certificate
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-bootstrap
spec:
  selfSigned: {}
---
# Step 2: A CA certificate issued by the bootstrap issuer
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-ca
spec:
  isCA: true
  commonName: my-documentdb-ca
  secretName: my-ca-secret
  duration: 8760h   # 1 year
  issuerRef:
    name: selfsigned-bootstrap
    kind: Issuer
---
# Step 3: A CA issuer that signs certificates using the CA certificate
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: my-ca-issuer
spec:
  ca:
    secretName: my-ca-secret

CertManager mode lets you use your own cert-manager Issuer (namespace-scoped) or ClusterIssuer (cluster-scoped) to issue TLS certificates for the DocumentDB gateway. This is ideal for production environments that already have PKI infrastructure (for example, a corporate CA).

Set issuerRef.name and issuerRef.kind to match your Issuer or ClusterIssuer. The operator will automatically request a certificate and mount it in the gateway.

documentdb-tls-certmanager.yaml
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: default
spec:
  nodeCount: 1
  instancesPerNode: 3
  resource:
    storage:
      pvcSize: 100Gi
  exposeViaService:
    serviceType: ClusterIP
  tls:
    gateway:
      mode: CertManager
      certManager:
        issuerRef:
          name: my-ca-issuer # (1)!
          kind: Issuer # (2)!
        dnsNames: # (3)!
          - documentdb.example.com
        secretName: my-documentdb-tls # (4)!
  1. Must match the metadata.name of your Issuer or ClusterIssuer (e.g., my-ca-issuer from the prerequisite example above).
  2. Use ClusterIssuer for cluster-scoped issuers, or Issuer for namespace-scoped.
  3. Subject Alternative Names — add all DNS names clients will use to connect.
  4. Optional. The Kubernetes Secret where cert-manager stores the issued certificate — you do not need to create this Secret yourself, cert-manager generates it automatically. Defaults to <documentdb-name>-gateway-cert-tls if not specified.

For a complete list of CertManager fields, see CertManagerTLS in the API Reference.

Connect with mongosh:

If your CA is private (which most cert-manager setups are), you need --tlsCAFile so mongosh can verify the server certificate:

# Extract the CA certificate from the Secret
kubectl get secret my-documentdb-tls -n default \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

# Connect with TLS
mongosh "mongodb://<username>:<password>@<host>:10260/?directConnection=true&authMechanism=SCRAM-SHA-256" \
  --tls --tlsCAFile ca.crt

Best for: Production with centralized certificate management

Prerequisites

A Kubernetes TLS Secret containing tls.crt and tls.key.

Creating a TLS Secret 
kubectl create secret generic my-documentdb-tls -n default \
  --from-file=tls.crt=server.crt \
  --from-file=tls.key=server.key \
  --from-file=ca.crt=ca.crt  # (1)!
  1. Optional. The gateway only uses tls.crt and tls.key. Including ca.crt stores the CA certificate in the same Secret for easy client-side retrieval.

Provided mode lets you supply your own TLS certificates. This is ideal when certificates are managed externally (for example, from Azure Key Vault, HashiCorp Vault, or a corporate CA).

documentdb-tls-provided.yaml
apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-documentdb
  namespace: default
spec:
  nodeCount: 1
  instancesPerNode: 3
  resource:
    storage:
      pvcSize: 100Gi
  exposeViaService:
    serviceType: ClusterIP
  tls:
    gateway:
      mode: Provided
      provided:
        secretName: my-documentdb-tls

Connect with mongosh:

If your CA is private, you need --tlsCAFile so mongosh can verify the server certificate:

# Connect with TLS using your CA certificate
mongosh "mongodb://<username>:<password>@<host>:10260/?directConnection=true&authMechanism=SCRAM-SHA-256" \
  --tls --tlsCAFile ca.crt

Certificate Rotation

Certificate rotation is automatic and zero-downtime. When a certificate is renewed, the gateway picks up the new certificate without restarting pods.

Mode Rotation Action required
SelfSigned cert-manager auto-renews 15 days before the 90-day expiry None
CertManager cert-manager auto-renews based on the Certificate CR's renewBefore None
Provided You update the Secret contents (manually or via CSI driver sync) Update the Secret

Note

Changing spec.tls.gateway.provided.secretName to point to a different Secret triggers a rolling restart of the DocumentDB cluster pods, which causes a brief period of downtime. To rotate certificates without downtime, update the contents of the existing Secret instead of changing the Secret name.

Monitoring Certificate Expiration

# Check certificate status via cert-manager
kubectl get certificate -n <namespace>

# Check expiration date
kubectl get secret <tls-secret> -n <namespace> \
  -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates

# Check DocumentDB TLS status
kubectl get documentdb <name> -n <namespace> \
  -o jsonpath='{.status.tls}' | jq

Example TLS status output:

{
  "ready": true,
  "secretName": "my-documentdb-gateway-cert-tls",
  "message": "Gateway TLS certificate ready"
}

Additional Resources

The documentdb-playground/tls/ directory provides automated scripts and end-to-end guides for TLS setup on AKS: