Atlas Kubernetes Operator
Parent: MongoDB Atlas · Published reference · snapshot 2026-09-08 · skill mongodb-atlas-expert/references/mongodb-atlas-kubernetes-operator.md
↓ Facts as markdownall context files
AKO lets you manage MongoDB Atlas cloud resources (clusters, users, networking, backup, search) as Kubernetes Custom Resources. Declare desired state in YAML; the operator reconciles against the Atlas
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
MongoDB Atlas Kubernetes Operator (AKO)
- AKO lets you manage MongoDB Atlas cloud resources (clusters, users, networking, backup, search) as Kubernetes Custom Resources. Declare desired state in YAML; the operator reconciles against the Atlas Administration API continuously. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#mongodb-atlas-kubernetes-operator-ako]
- Latest stable: v2.14.1 (May 2026) · GitHub: mongodb/mongodb-atlas-kubernetes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#mongodb-atlas-kubernetes-operator-ako]
Namespace Scoping
- By default AKO watches all namespaces. For multi-tenant clusters: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#namespace-scoping]
Independent vs Subobject CRDs
- Subobject CRDs: Embedded in AtlasProject (e.g., spec.alertConfigurations) - managed as part of the project [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#independent-vs-subobject-crds]
- Independent CRDs: Deployed as separate Kubernetes objects - can be owned and managed by different teams (e.g., application teams own their AtlasDatabaseUser) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#independent-vs-subobject-crds]
GitOps Workflow with AKO
- AKO integrates natively with ArgoCD and Flux. The operator continuously reconciles the declared state in Git against Atlas. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#gitops-workflow-with-ako]
- Dry-run validation: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#gitops-workflow-with-ako]
Workload Identity (Passwordless Atlas API Access)
- Instead of storing Atlas API key credentials in a Kubernetes Secret, use Workload Identity to have the AKO pod authenticate using a cloud-provider IAM identity: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#workload-identity-passwordless-atlas-api-access]
AWS (IRSA)
- Create IAM role with Atlas permissions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aws-irsa]
- Annotate AKO service account with eks.amazonaws.com/role-arn [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aws-irsa]
- AKO uses IRSA to get tokens for Atlas Service Account [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aws-irsa]
GKE (Workload Identity)
- Annotate AKO service account with iam.gke.io/gcp-service-account [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#gke-workload-identity]
- Bind GCP SA to Atlas Service Account via OIDC federation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#gke-workload-identity]
AKS (Workload Identity)
- Use azure.workload.identity/use: "true" on AKO pod [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aks-workload-identity]
- Federate AKS OIDC issuer with Atlas Service Account [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aks-workload-identity]
Reconciliation: Troubleshooting
- Cluster stuck in UPDATING: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Check AKO logs: kubectl logs -n atlas-operator deploy/mongodb-atlas-operator [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Describe the AtlasDeployment: check status.conditions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Atlas API limits may cause reconciliation delays - check Atlas UI [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- "invalid credentials" error: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Verify the Secret referenced in connectionSecretRef exists in the correct namespace [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Check the API key has the required Atlas project roles (at minimum GROUP_CLUSTER_MANAGER) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- AKO not reconciling changed CRD: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Verify the CRD version matches the installed AKO version [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
- Use kubectl get events -n <namespace> to see reconciliation events [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting]
Common Anti-Patterns
- Manual UI changes on AKO-managed resources: AKO will reconcile them away on next cycle [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#common-anti-patterns]
- Storing Atlas API keys in plain Kubernetes Secrets without encryption: Use SealedSecrets, External Secrets Operator, or Workload Identity [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#common-anti-patterns]
- Not scoping AKO to specific namespaces in multi-tenant clusters: AKO with cluster-wide watch can interfere with other applications' secrets [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#common-anti-patterns]
- Upgrading AKO without reading the changelog: Major AKO versions introduce CRD schema changes that require migration [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#common-anti-patterns]
References
- AKO Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references]
- AKO GitHub [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references]
- AKO Helm Chart [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references]
- atlas kubernetes config generate [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references]
Where this helps
- Managing Atlas clusters, users, networking, backup, and search as Kubernetes Custom Resources so cluster state lives declaratively in Git rather than being clicked together in the Atlas UI. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Setting up a GitOps workflow (ArgoCD or Flux) where the operator continuously reconciles the declared state in Git against the live Atlas project. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Eliminating stored Atlas API key credentials by using cloud-provider Workload Identity (AWS IRSA, GKE Workload Identity, AKS Workload Identity) so the AKO pod authenticates without a Kubernetes Secret holding a raw key. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Troubleshooting a cluster stuck in an UPDATING state or an 'invalid credentials' reconciliation error by walking the operator's logs, the AtlasDeployment status conditions, and the referenced connection Secret. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Stand up AKO with namespace scoping in a multi-tenant cluster so application teams can own their own AtlasDatabaseUser resources without AKO's watch interfering with unrelated namespaces. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Wire AKO into an existing ArgoCD or Flux pipeline with dry-run validation so a proposed Atlas cluster or user change is checked before it's applied. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Migrate an AKO deployment from a stored API-key Secret to cloud-provider Workload Identity (IRSA on AWS, Workload Identity on GKE, or the Azure equivalent on AKS) to remove long-lived credentials from the cluster. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a reconciliation-health dashboard that surfaces AtlasDeployment status.conditions and AKO logs, so a stuck-in-UPDATING cluster or a credential error is caught before it becomes a support case. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Making manual changes to an AKO-managed resource in the Atlas UI — AKO will reconcile them away on the next cycle, silently reverting the manual change. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Storing Atlas API keys in a plain Kubernetes Secret with no additional protection, instead of using SealedSecrets, an External Secrets Operator, or Workload Identity. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Running AKO with cluster-wide namespace watch in a multi-tenant cluster, letting it interfere with other applications' secrets and resources. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Upgrading AKO to a new major version without reading the changelog first — major versions can introduce CRD schema changes that require an explicit migration step. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Independent CRDs (like AtlasDatabaseUser) can be owned by a different team than the AtlasProject that contains them, which is powerful for delegation but means ownership boundaries need to be planned deliberately, not left implicit. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Atlas API rate limits can cause reconciliation delays that look like an AKO bug but are actually the operator waiting on the Atlas API — worth checking the Atlas UI for API throttling before assuming AKO itself is broken. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A CRD version mismatch between the installed AKO version and the applied manifest is a documented cause of AKO silently not reconciling a changed resource. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- This pack's own reference list is thin (four items) relative to the depth of the reconciliation-troubleshooting section, so some workload-identity federation details may need cross-checking against the current AKO docs before production use. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.