Atlas Kubernetes Operator

Parent: MongoDB Atlas · researched 2026-05-28T18:37:58.382Z· 22 sources · 18 concepts · skill mongodb-atlas-kubernetes-operator

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

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. [source]
Latest stable: v2.14.1 (May 2026) · GitHub: mongodb/mongodb-atlas-kubernetes [source]

Namespace Scoping

By default AKO watches all namespaces. For multi-tenant clusters: [source]

Independent vs Subobject CRDs

Subobject CRDs: Embedded in AtlasProject (e.g., spec.alertConfigurations) - managed as part of the project [source]
Independent CRDs: Deployed as separate Kubernetes objects - can be owned and managed by different teams (e.g., application teams own their AtlasDatabaseUser) [source]

GitOps Workflow with AKO

AKO integrates natively with ArgoCD and Flux. The operator continuously reconciles the declared state in Git against Atlas. [source]
Dry-run validation: [source]

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: [source]

AWS (IRSA)

Create IAM role with Atlas permissions [source]
Annotate AKO service account with eks.amazonaws.com/role-arn [source]
AKO uses IRSA to get tokens for Atlas Service Account [source]

GKE (Workload Identity)

Annotate AKO service account with iam.gke.io/gcp-service-account [source]
Bind GCP SA to Atlas Service Account via OIDC federation [source]

AKS (Workload Identity)

Use azure.workload.identity/use: "true" on AKO pod [source]
Federate AKS OIDC issuer with Atlas Service Account [source]

Reconciliation: Troubleshooting

Cluster stuck in UPDATING: [source]
Check AKO logs: kubectl logs -n atlas-operator deploy/mongodb-atlas-operator [source]
Describe the AtlasDeployment: check status.conditions [source]
Atlas API limits may cause reconciliation delays - check Atlas UI [source]
"invalid credentials" error: [source]
Verify the Secret referenced in connectionSecretRef exists in the correct namespace [source]
Check the API key has the required Atlas project roles (at minimum GROUP_CLUSTER_MANAGER) [source]
AKO not reconciling changed CRD: [source]
Verify the CRD version matches the installed AKO version [source]
Use kubectl get events -n <namespace> to see reconciliation events [source]

Common Anti-Patterns

Manual UI changes on AKO-managed resources: AKO will reconcile them away on next cycle [source]
Storing Atlas API keys in plain Kubernetes Secrets without encryption: Use SealedSecrets, External Secrets Operator, or Workload Identity [source]
Not scoping AKO to specific namespaces in multi-tenant clusters: AKO with cluster-wide watch can interfere with other applications' secrets [source]
Upgrading AKO without reading the changelog: Major AKO versions introduce CRD schema changes that require migration [source]

References

AKO Documentation [source]
AKO GitHub [source]
AKO Helm Chart [source]
atlas kubernetes config generate [source]

Children

AKO CRDs (frontier)
AKO GitOps (frontier)
AKO Workload Identity (frontier)
AKO Helm Installation (frontier)
AKO Troubleshooting (frontier)
AKO vs Terraform (frontier)

Frontier under this node: AKO CRDs, AKO GitOps, AKO Helm Installation, AKO Troubleshooting, AKO Workload Identity, AKO vs Terraform

← the whole tree · 3D view· how to read this page