DOCSEARCHbyAlgolia
Submit Docs

MongoDB Community Kubernetes Operator

repository·master·Indexed 23 days ago

https://github.com/mongodb/mongodb-kubernetes-operator

A Kubernetes Operator that automates the deployment, management, and scaling of MongoDB Community Edition replica sets. Key features include replica set management, always-up server version upgrades/downgrades, Prometheus metrics integration, TLS security, and SCRAM authentication. Note: This repository is deprecated and will receive best-effort support until November 2025; users are encouraged to migrate to the unified mongodb-kubernetes repository.

Tokens
16.3K
Snippets
41
Records
78
Agent score
80%

What's inside mongodb-kubernetes-operator

  1. Overview of MongoDB Community Kubernetes Operator features

    master

    The MongoDB Community Kubernetes Operator is a Kubernetes Operator designed to deploy and manage MongoDB Community editions within Kubernetes clusters.

    Core Capabilities:

    • Replica Set Management: Create, scale up, and scale down replica sets.
    • Lifecycle Operations: Perform server version upgrades and downgrades in an "always up" manner (allowing reads and writes during the process).
    • Observability: Report MongoDB server state via the status field of the MongoDBCommunity resource and enable a metrics target for use with Prometheus.
    • Security:
      • Secure client-to-server and server-to-server connections using TLS.
      • Create users with SCRAM authentication.
      • Create custom roles.
    • Flexibility: Use any available Docker MongoDB images.
    • Connectivity: Connect to the replica set from within the Kubernetes cluster (no external connectivity provided by default).

    Important Note for Enterprise Users: If you require Enterprise features such as Backup, do not use this operator. Instead, use the MongoDB Enterprise Operator for Kubernetes.

  2. How the MongoDB Community Kubernetes Operator manages clusters

    master

    The operator functions as a Kubernetes Controller and uses a MongoDBCommunity Custom Resource Definition (CRD) to manage MongoDB deployments.

    When a MongoDBCommunity resource is applied, the Operator performs the following:

    1. StatefulSet Creation: Creates a StatefulSet where each pod represents a member of a MongoDB replica set.
    2. Pod Structure: Each pod contains three distinct containers:
      • Init Container: Copies the cmd/versionhook binary to the mongod container to handle version upgrades.
      • mongod Container: The primary database daemon process.
      • MongoDB Agent Container: Handles automation tasks like configuring, stopping, and restarting the mongod process. It periodically polls mongod to ensure the desired state is met.
    3. Storage and Configuration:
      • data-volume: A persistent volume mounted at /data for both the server and agent. It stores server data, automation-mongod.conf, and agent locks.
      • automation-config: A Secret containing automation configuration, mounted to both containers (lives for the duration of the pod).
      • healthstatus: A volume used to share the agent's status with the mongod container for use in pre-stop hooks.

    Key Architectural Benefits

    • Decoupled Lifecycles: The mongod container is independent of the Agent and the Operator. You can upgrade the Operator or Agent without affecting the database uptime or the database image.
    • Immutability: Containers follow the single-responsibility principle, allowing for independent resource configuration, logging, and debugging.
    • Stable Identities: Uses StatefulSets to ensure pods have stable network identities.
    • Offline Capability: Clusters can be set up offline by pre-downloading the database and MongoDB Agent Docker images.

  3. Understand MongoDB Community Operator deployment scopes

    master

    The MongoDB Community Kubernetes Operator can be deployed with two different scopes, determining which namespaces it manages:

    1. Operator in Same Namespace as Resources (Default): The Operator is scoped to a specific namespace and only watches MongoDBCommunity resources within that same namespace. This is the behavior when using Helm or kubectl without additional configuration.
    2. Operator in Different Namespace Than Resources: The Operator is deployed in one namespace but is configured to watch MongoDBCommunity resources in other namespaces. This is useful for centralized management.

  4. How MongoDB version upgrades work

    master

    The Operator manages rolling upgrades via the MongoDB Agent's Automation function. To prevent multiple re-elections that can occur with native Kubernetes rolling updates, the Operator overrides the standard process.

    Upgrade Workflow

    When you update the MongoDB version in your MongoDBCommunity resource definition and reapply it, the following sequence occurs:

    1. Strategy Shift: The Operator changes the StatefulSet update strategy from RollingUpdate to OnDelete.
    2. Configuration Update: The Operator updates the image specification to the new version and writes a new Automation configuration to each pod.
    3. Controlled Shutdown: The MongoDB Agent selects the first pod and stops mongod using db.shutdownServer via a local connection.
    4. Version Hook: Kubernetes restarts the mongod container. The versionhook (from the init container) runs first. If the Agent expects a new version, the hook deletes the pod via a Kubernetes API call.
    5. Pod Replacement: Kubernetes restarts the pod with the new mongod image.
    6. Agent Re-initialization: The MongoDB Agent starts, verifies the new mongod version, generates the configuration, and starts the mongod process.
    7. Sequential Progression: The Agent repeats this process for the next pod until all members are upgraded.
    8. Restoration: The Operator changes the StatefulSet update strategy back to RollingUpdate.

    Advantages of this approach

    • Upgrades secondaries before primaries.
    • Ensures secondaries' oplogs are caught up before triggering elections.
    • Maintains replica set availability throughout the entire process.

  5. How the MongoDB Operator architecture works

    master

    The operator consists of a single image containing the operational logic to deploy and maintain MongoDBCommunity resources. When deploying MongoDB, the operator uses a StatefulSet where each Pod contains multiple coexisting images:

    • Agent image: Includes a MongoDB-provided binary that handles local server operations based on configurations provided via a ConfigMap mounted in the Pod.
    • MongoDB image: The standard Docker image containing the MongoDB server.
    • Version upgrade post-start hook image: Orchestrates Replica Set member restarts during version upgrades to ensure seamless, zero-downtime operations.

    Each Pod represents a member of a Replica Set and manages different parts of the database lifecycle.

  7. Migrate to the new MongoDB Kubernetes repository

    master

    DEPRECATED

    This repository is deprecated and will receive best-effort support only until November 2025.

    To continue using MongoDB in Kubernetes, you should migrate to the new, unified repository: mongodb/mongodb-kubernetes.

    Migration Resources:

    Note that there are no functional changes in the new repository; it provides a unified experience and improved visibility into the development process.

  8. Retrieve TLS Certificates from MongoDB Pod

    master

    To connect via TLS from outside the cluster, you need the server certificate generated by the pod.

    1. Exec into the first member of the replica set:
    kubectl exec --namespace <your-namespace> -it <mongodb-name>-0 -c mongod -- bash
    1. Inside the container, locate the .pem file in /var/lib/tls/server.
    2. cat the file and copy its contents to a local file (e.g., key.pem) on your machine.

  9. Rotate TLS certificates for a MongoDB deployment

    master

    To rotate TLS certificates, you must renew the Kubernetes secret specified under Spec.Security.TLS.CertificateKeySecret.Name.

    If you are using cert-manager, follow the standard cert-manager renewal process. The operator watches for changes to the secret and will automatically trigger a reconciliation process once the secret is updated.

    To manually rotate the secret using existing certificate and key files, use the following command pattern:

    kubectl create secret tls <secret_name> \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

  11. Run the MongoDB Kubernetes Operator locally

    master

    To run the operator binary locally for faster feedback cycles, you must first configure your config.json file (referenced in the contributing guide) with two specific fields required by the local execution script:

    1. mdb_local_operator: Set to true to enable local execution mode.
    2. kubeconfig: Set to the absolute path of your Kubernetes configuration file (e.g., $HOME/.kube/config).

    Ensure you have a valid Kubernetes context available via $HOME/.kube/config or the KUBECONFIG environment variable. You can also optionally source the generated environment variables using source .community-operator-dev/local-test.export.env if you have run make generate-env-file.

  12. Deploy a MongoDB Resource with Prometheus metrics

    master

    You can deploy a MongoDB resource that includes a ServiceMonitor to automatically indicate to Prometheus how to consume its metrics.

    Using the provided mongodb-prometheus-sample.yaml creates:

    1. A MongoDB resource with one user.
    2. Two Secrets in the mongodb namespace (one for MongoDB user authentication and one for basic HTTP authentication for the Prometheus endpoint).
    3. A ServiceMonitor in the prometheus-system namespace to configure Prometheus scraping.

    If you have not cloned the repository, use the raw URL to apply the sample.