# 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 Parent: [MongoDB Atlas](https://llms-explorer.com/tree/mongodb-atlas/) · 15 facets · 49 facts · page: https://llms-explorer.com/tree/atlas-kubernetes-operator/ ## 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](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 — [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: — [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 — [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) — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#gitops-workflow-with-ako) - Dry-run validation: — [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: — [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 — [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 — [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 — [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 — [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 — [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 — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aks-workload-identity) - Federate AKS OIDC issuer with Atlas Service Account — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#aks-workload-identity) ## Reconciliation: Troubleshooting - Cluster stuck in UPDATING: — [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 — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting) - Describe the AtlasDeployment: check status.conditions — [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 — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting) - "invalid credentials" error: — [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 — [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) — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting) - AKO not reconciling changed CRD: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting) - Verify the CRD version matches the installed AKO version — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#reconciliation-troubleshooting) - Use kubectl get events -n to see reconciliation events — [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 — [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 — [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 — [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 — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#common-anti-patterns) ## References - AKO Documentation — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references) - AKO GitHub — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references) - AKO Helm Chart — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator/#references) - atlas kubernetes config generate — [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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(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](https://llms-explorer.com/tree/atlas-kubernetes-operator/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [Atlas Kubernetes Operator](https://llms-explorer.com/downloads/sources/mdb-context-hub/mongodb-atlas-kubernetes-operator.md)