MongoDB Atlas Infrastructure as Code
Parent: MongoDB Atlas · Published reference · snapshot 2026-09-08 · skill mongodb-atlas-expert/references/mongodb-atlas-iac.md
↓ Facts as markdownall context files
All Atlas IaC tools call the same cloud.mongodb.com/api/atlas/v2/ endpoints under OAuth 2.0 or HTTP Digest authentication. Tool choice depends on where platform engineering already lives.
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.
Overview
- All Atlas IaC tools call the same cloud.mongodb.com/api/atlas/v2/ endpoints under OAuth 2.0 or HTTP Digest authentication. Tool choice depends on where platform engineering already lives. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- Current versions (May 2026): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- Terraform provider (mongodb/mongodbatlas): v2.12.0 - 72.5M downloads [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- Atlas Kubernetes Operator (AKO): v2.14 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- Atlas Admin API: v2 (v1.0 deprecated) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- AWS CloudFormation resources: 33+ resource types [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
- AWS CDK: awscdk-resources-mongodbatlas [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#overview]
Service Accounts (OAuth 2.0) — Recommended (GA April 2025)
- Client ID + Client Secret → short-lived bearer tokens (1-hour TTL). Scoped at Organization or Project level. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
- Why preferred over API Keys: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
- Industry-standard OAuth 2.0 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
- Client Secret rotation without changing Client ID [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
- Workload Identity Federation (WIF) - replace static secrets on GKE/AKS/EKS/Cloud Run [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
- Better support in modern Atlas tooling [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#service-accounts-oauth-20-recommended-ga-april-2025]
Programmatic API Keys (HTTP Digest) — Legacy
- public_key:private_key pair. Cannot be rotated atomically; counted as "users" in project member list. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#programmatic-api-keys-http-digest-legacy]
Key Migration: v1 → v2 (Breaking Changes)
- mongodbatlas_cluster → mongodbatlas_advanced_cluster (provider v2.0) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#key-migration-v1-v2-breaking-changes]
Drift Detection
- Terraform detects drift in terraform plan. Atlas API changes made outside Terraform (via UI or CLI) cause drift. Use terraform import to bring unmanaged resources under Terraform control. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#drift-detection]
Independent vs Subobject CRDs
- Subobject CRDs: Managed as fields in AtlasProject (e.g., spec.alertConfigurations) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#independent-vs-subobject-crds]
- Independent CRDs: Deployed as separate Kubernetes objects, can be managed by different teams [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#independent-vs-subobject-crds]
Pulumi (MongoDB Atlas Provider)
- Parity with Terraform via bridge. Python, Node.js, Go, Java, .NET support. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#pulumi-mongodb-atlas-provider]
AWS CloudFormation
- 33+ MongoDB resource types prefixed MongoDB::Atlas::*. Notable: MongoDB::Atlas::Cluster, MongoDB::Atlas::Project, MongoDB::Atlas::DatabaseUser. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#aws-cloudformation]
- Note: Do NOT use MongoDB::Atlas::FlexCluster - use MongoDB::Atlas::Cluster instead (FlexCluster resource will not receive future updates). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#aws-cloudformation]
Multi-Environment Patterns
- Use Terraform workspaces or separate state files per environment. Never share a single state file across dev/staging/prod. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#multi-environment-patterns]
Common Anti-Patterns
- Manual UI changes on Terraform-managed resources: Causes drift; must re-run terraform apply to reconcile [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#common-anti-patterns]
- Using legacy mongodbatlas_cluster resource: Removed in provider v2.0; use mongodbatlas_advanced_cluster [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#common-anti-patterns]
- Storing Service Account client secrets in Terraform state: Use Vault, AWS Secrets Manager, or external secrets operator [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#common-anti-patterns]
- Shared Terraform state across environments: Risk of accidental cross-environment changes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#common-anti-patterns]
- Not pinning provider versions: Atlas IaC tools update frequently; pin to a specific version range [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#common-anti-patterns]
References
- Terraform Provider Registry [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#references]
- Atlas Kubernetes Operator GitHub [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#references]
- Atlas Admin API v2 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#references]
- Atlas Service Accounts [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iac/#references]
Where this helps
- Deciding which Atlas IaC tool fits an existing platform-engineering stack — Terraform, the Atlas Kubernetes Operator, Pulumi, or AWS CloudFormation/CDK — since they all call the same underlying Admin API v2. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Migrating Atlas automation authentication from legacy Programmatic API Keys (HTTP Digest) to OAuth 2.0 Service Accounts. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Diagnosing Terraform drift after someone made a manual change to an Atlas cluster or project through the UI. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Structuring multi-environment Atlas IaC across dev/staging/prod so a mistake in one environment's state can't touch another's. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Migrate an existing Terraform Atlas configuration from Programmatic API Keys to a Service Account with OAuth 2.0 client credentials, storing the client secret in Vault or AWS Secrets Manager rather than Terraform state. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build separate Terraform state files, or workspaces, per environment for an Atlas project family, and add a CI check that fails the plan if cross-environment resources are referenced. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Prototype the same cluster provisioning logic in both the Atlas Kubernetes Operator, using an Independent CRD, and Terraform, to compare which fits a Kubernetes-native platform team better. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Write a CI job that runs terraform plan on a schedule against Atlas-managed infrastructure to detect and alert on drift caused by manual UI changes. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Making manual changes in the Atlas UI to a Terraform-managed resource, which causes drift that only gets reconciled on the next terraform apply. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Continuing to reference the legacy mongodbatlas_cluster resource after upgrading to provider v2.0, where it was removed in favor of mongodbatlas_advanced_cluster. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Storing Service Account client secrets directly in Terraform state instead of a secrets manager or external-secrets operator. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Sharing a single Terraform state file across dev/staging/prod, risking an accidental change to the wrong environment. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Not pinning the Atlas Terraform provider version is risky because Atlas IaC tooling updates frequently, and an unpinned provider can pull in breaking changes on the next init. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- AWS CloudFormation's MongoDB::Atlas::FlexCluster resource type is effectively frozen — it will not receive future updates, so MongoDB::Atlas::Cluster should be used instead even for Flex clusters. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The v1-to-v2 Terraform provider migration involves genuine breaking changes, mongodbatlas_cluster to mongodbatlas_advanced_cluster among them, so it isn't a drop-in version bump. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Independent CRDs in the Atlas Kubernetes Operator can be managed by different teams, which is powerful but also means ownership boundaries have to be established deliberately or resources can conflict. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Terraform Atlas Provider v2.x (frontier, viability 3.58 / 5)
- Atlas Kubernetes Operator AKO v2.14 (frontier, viability 3.42 / 5)
- Atlas CLI Scripting (frontier, viability 3.50 / 5)
- Atlas Admin API v2 REST (frontier, viability 3.75 / 5)
- Pulumi mongodbatlas Provider (frontier, viability 4.00 / 5)
- AWS CloudFormation Atlas Resources
- AWS CDK awscdk-resources-mongodbatlas
- Service Account OAuth 2.0 Authentication (frontier, viability 4.05 / 5)
- Programmatic API Keys Legacy Auth (frontier, viability 3.05 / 5, below research gate)
- mongodbatlas_advanced_cluster Resource (frontier, viability 4.33 / 5)
- moved Block Migration Pattern (frontier, viability 3.63 / 5)
- Terraform Drift Detection (frontier, viability 3.83 / 5)
- AKO Independent CRDs
- AKO Subobject CRDs Deprecated
- AKO Dry Run Mode (frontier, viability 3.05 / 5, below research gate)
- AKO Deletion Protection v2.0 (frontier, viability 3.55 / 5)
- AKO Reconciliation Skip Annotation
- Atlas CLI Terraform Plugin (frontier, viability 3.20 / 5)
- atlas kubernetes config generate (frontier, viability 3.15 / 5, below research gate)
- Multi-Environment Terraform Directories vs Workspaces (frontier, viability 3.13 / 5, below research gate)
- Service Account per Environment Pattern (frontier, viability 3.27 / 5)
- Backup Compliance Policy One-Way (frontier, viability 3.83 / 5)
- Atlas IP Access List Ownership Conflict (frontier, viability 3.52 / 5)
- Terraform Import generate-config-out (frontier, viability 3.73 / 5)
- Workload Identity Federation Atlas (frontier, viability 4.08 / 5)
- Atlas Admin API Date Versioned Media Types (frontier, viability 4.08 / 5)
- CloudFormation Third Party Activation (frontier, viability 3.63 / 5)
- Atlas IaC Migration Paths (frontier, viability 3.60 / 5)
- Atlas IaC Anti-Patterns (frontier, viability 3.15 / 5, below research gate)
- Atlas IaC Tool Decision Matrix (frontier, viability 3.45 / 5)
Frontier under this node: AKO Deletion Protection v2.0 (3.55), AKO Dry Run Mode (3.05), Atlas Admin API Date Versioned Media Types (4.08), Atlas Admin API v2 REST (3.75), Atlas CLI Scripting (3.50), Atlas CLI Terraform Plugin (3.20), Atlas IP Access List Ownership Conflict (3.52), Atlas IaC Anti-Patterns (3.15), Atlas IaC Migration Paths (3.60), Atlas IaC Tool Decision Matrix (3.45), Atlas Kubernetes Operator AKO v2.14 (3.42), Backup Compliance Policy One-Way (3.83), CloudFormation Third Party Activation (3.63), Multi-Environment Terraform Directories vs Workspaces (3.13), Programmatic API Keys Legacy Auth (3.05), Pulumi mongodbatlas Provider (4.00), Service Account OAuth 2.0 Authentication (4.05), Service Account per Environment Pattern (3.27), Terraform Atlas Provider v2.x (3.58), Terraform Drift Detection (3.83), Terraform Import generate-config-out (3.73), Workload Identity Federation Atlas (4.08), atlas kubernetes config generate (3.15), mongodbatlas_advanced_cluster Resource (4.33), moved Block Migration Pattern (3.63)