MongoDB Atlas Operator (AKO)

The MongoDB Atlas Operator provides native integration between Kubernetes and MongoDB Atlas. It allows you to manage MongoDB Atlas resources directly through Kubernetes using Custom Resources.

Key capabilities include:

• Managing Atlas Projects (creating new ones or connecting to existing ones).
• Lifecycle management of Atlas clusters (deploy, scale, manage, and tear down).
• Support for Atlas serverless instances.
• Database user management.
• Network configuration (IP Access Lists, network peering, and private endpoints).
• Managing Atlas cloud backup.
• Configuring federated authentication for Atlas organizations.
• Integrating Atlas monitoring with Prometheus.

The SRE Runbook collection provides documentation for troubleshooting common incidents and anomalies encountered when operating the Atlas Kubernetes Operator (AKO). Each runbook is designed to help you identify, diagnose, and resolve issues by providing:

• A description of the problem and its symptoms.
• Diagnostic metrics to monitor.
• Step-by-step resolution actions.
• Links to related documentation.

Use this index to navigate to specific troubleshooting guides based on the symptoms you are observing in your AKO deployment.

The MongoDB Atlas Kubernetes Operator consumes credentials from Kubernetes Secrets and continuously monitors them for changes. This allows you to use automated secret management tools like External Secrets to provision credentials (such as Atlas credentials and DB User Passwords) directly from external providers into your Kubernetes cluster.

Commonly supported External Secrets providers include:

• Hashicorp Vault
• AWS Secrets Manager or Parameters Store
• Azure Key Vault
• Google Cloud Secret Manager

The MongoDB Atlas Operator is distributed on OpenShift using the Operator Lifecycle Manager (OLM). This process relies on three core components:

• ClusterServiceVersion (CSV): The primary manifest describing the operator. It includes the name, version, description, install strategy, owned CRDs, required permissions, and the replaces field which defines the upgrade path.
• Bundle: A directory (and its corresponding container image) that packages the CSV, CRDs, and OLM metadata. When generated locally, it resides in the bundle/ directory.
• Catalog: A registry of bundles used by OLM to discover and install operators. Catalogs are built using make catalog-build.

The project follows these core testing principles:

• Prefer reliable, fast, and focused tests over end-to-end (e2e) testing. E2E tests are the "last line of defense" and should be used sparingly due to cost and CI feedback latency.
• Start with a spec: Define detailed behavior before implementation to inform test requirements.
• Prefer TDD (Test Driven Development): Write unit tests before implementation to force cleaner interfaces and simpler functions.
• Prefer external tests: In Go, use package xxx_test instead of package xxx to ensure you are testing the public API/behavior rather than internal implementation details.
• Exploratory testing: Use temporary tests to learn how dependencies (Atlas, Cloud APIs, Kubernetes) behave, but do not let these become your final e2e tests.

The AtlasDeployment.status field provides the observed state of your cluster.

Cluster State

• stateName (string): The current state of the cluster. Possible values: IDLE, CREATING, UPDATING, DELETING, DELETED, REPAIRING.
• observedGeneration (integer): The generation of the resource specification the operator is currently reconciling.
• mongoDBVersion (string): The version of MongoDB running in <major>.<minor> format.

Conditions

The conditions array contains a list of statuses showing the current state of the Custom Resource. Each condition includes:

• status (string): One of True, False, Unknown.
• type (string): The type of the condition.
• lastTransitionTime (string): ISO 8601 timestamp of the last transition.
• message (string): Details about the transition.
• reason (string): The reason for the last transition.

OpenShift certification validates container images for Red Hat's OpenShift platform using Red Hat's preflight tool. The certification process via the certify-openshift-images.sh script operates in two distinct modes:

1. Check Only (SUBMIT=false): A non-destructive mode that runs validation locally and reports results. It does not write to Red Hat. This is safe for testing and pre-release verification.
2. Submit (SUBMIT=true): A destructive mode that writes certification results to Red Hat's Pyxis API, making the certification official. This is a point of no return and should only be used for official releases.

When using multi-tenant clusters, if the providerName is TENANT and electableSpecs.instanceSize is set to M2 or M5, MongoDB Cloud will create a Flex cluster instead of a standard cluster.

Warning: Support for M2 and M5 instance sizes will be discontinued in January 2026. It is recommended to use the dedicated Create Flex Cluster API for these configurations.

The Cluster resource is managed by the MongoDB Kubernetes Atlas Operator. It allows you to define and manage MongoDB Atlas clusters directly through Kubernetes.

Key components of a Cluster resource include:

• apiVersion: Must be atlas.generated.mongodb.com/v1.
• kind: Must be Cluster.
• metadata: Standard Kubernetes object metadata.
• spec: The desired state of the cluster. It supports versioned specifications (e.g., v20250312). At most one versioned spec can be specified.
• status: The current observed state of the cluster, populated by the operator.

apiVersion: atlas.generated.mongodb.com/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  # versioned spec goes here
  v20250312:
    entry:
      # cluster configuration
      mongoDBMajorVersion: "6.0"

When using S3 as a data source, you can use advanced features in spec.storage.databases[].collections[].dataSources:

• Wildcard Collections: To create a wildcard collection, omit the collection parameter. You can use collectionRegex to define a regex pattern for the wildcard.
• Wildcard Databases: To generate wildcard databases, omit the database parameter. You can use databaseRegex to define a regex pattern.
• Views: You can define aggregation pipelines that apply to a collection using spec.storage.databases[].views.
  • name: The name of the view.
  • pipeline: The aggregation pipeline stages to apply.
  • source: The source collection for the view.

The stateName field provides a human-readable label indicating current activity on the cluster by the Atlas control plane. Most states allow the cluster to remain available with a Primary node, except for CREATING and DELETING.

• IDLE: No changes in progress; all requested changes are applied.
• CREATING: Cluster is being provisioned. Ensure IP Access Lists and DB Users are configured before connecting.
• UPDATING: A change is being applied (via UI, API, AutoScaling, etc.).
• DELETING: The cluster is being removed.
• REPAIRING: One or more nodes are being returned to service; other nodes continue to provide service.