MongoDB Atlas Terraform Provider
Parent: MongoDB Atlas · Published reference · snapshot 2026-09-08 · skill mongodb-atlas-expert/references/mongodb-atlas-terraform.md
↓ Facts as markdownall context files
The mongodb/mongodbatlas Terraform provider lets you manage the full lifecycle of MongoDB Atlas infrastructure as code. It covers clusters (dedicated, Flex replacing legacy serverless), networking (VP
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
- The mongodb/mongodbatlas Terraform provider lets you manage the full lifecycle of MongoDB Atlas infrastructure as code. It covers clusters (dedicated, Flex replacing legacy serverless), networking (VPC peering, Private Link), project/org management, database users, search indexes, encryption at rest, backups, and alert configurations. As of September 2025, provider v2.0.0 is the current major version with semantic versioning guarantees - minor and patch releases will not introduce breaking changes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#overview]
- Registry: registry.terraform.io/providers/mongodb/mongodbatlas GitHub: github.com/mongodb/terraform-provider-mongodbatlas [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#overview]
When to Use This Skill
- Provisioning Atlas clusters, networking, or users via Terraform [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Migrating from mongodbatlas_cluster (v1 legacy) to mongodbatlas_advanced_cluster (v2 preferred) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Debugging provider v1 → v2 breaking changes and upgrade errors [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Setting up Private Link, VPC peering, or network containers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Configuring encryption at rest (AWS KMS, Azure Key Vault, GCP KMS) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Writing search index resources or search node deployments [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Designing module interfaces for reusable Atlas IaC patterns [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
- Configuring Atlantis or Terraform Cloud for Atlas API key management [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-to-use-this-skill]
When NOT to Use This Skill
- Using Pulumi for MongoDB Atlas (use the Pulumi mongodbatlas package instead) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-not-to-use-this-skill]
- Using Crossplane for MongoDB Atlas (use the Crossplane MongoDB Atlas provider) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-not-to-use-this-skill]
- Using the Atlas Kubernetes Operator (mongodbatlas-kubernetes-operator skill covers that) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-not-to-use-this-skill]
- CloudFormation / CDK stacks for Atlas resources [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#when-not-to-use-this-skill]
Required Providers Block
- Pin a specific minor version to avoid unplanned upgrades: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#required-providers-block]
- For v1.x users not yet ready to migrate: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#required-providers-block]
Authentication Methods
- Method 1 - Environment Variables (recommended for CI/CD): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Provider block with no credentials (reads from env): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Method 2 - Explicit in provider block (use only with secrets injection): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Never hard-code keys in .tf files. Use HashiCorp Vault, AWS Secrets Manager, or TFC workspace variables. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Method 3 - Service Account (new in v2, recommended for production): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Atlas supports Service Accounts with OAuth 2.0 client credentials. The provider reads MONGODB_ATLAS_CLIENT_ID and MONGODB_ATLAS_CLIENT_SECRET environment variables: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- Note - AWS IAM Assumed Role (for resource-level cloud access, not provider auth): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
- The provider does not authenticate to Atlas via IAM. IAM assumed roles are used by Atlas to access your AWS resources (KMS, S3 export buckets). This is configured via mongodbatlas_cloud_provider_access_setup and mongodbatlas_cloud_provider_access_authorization resources - see Section 5 for the full three-step example. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#authentication-methods]
API Key IP Access List
- Programmatic API keys require IP access list entries. In production, add your Terraform Cloud / Atlantis egress IP range. You can use 0.0.0.0/0 for development but never for production. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#api-key-ip-access-list]
Version Pinning Best Practices
- Use ~> 2.7 (allows patch updates within 2.x, blocks 3.x) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#version-pinning-best-practices]
- Lock to an exact version in production, allow patch updates (~> 2.7) in dev/staging [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#version-pinning-best-practices]
- Run terraform init -upgrade explicitly when bumping the version constraint [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#version-pinning-best-practices]
- Check the CHANGELOG before any minor version bump for deprecation notices [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#version-pinning-best-practices]
2. Advanced Cluster Resource
- mongodbatlas_advanced_cluster is the preferred resource as of provider v1.18+ and the only cluster resource in v2.x (mongodbatlas_cluster was removed). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#2-advanced-cluster-resource]
Auto-Scaling Configuration
- Use use_effective_fields = true to eliminate lifecycle.ignore_changes blocks: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#auto-scaling-configuration]
- Import: terraform import mongodbatlas_advanced_cluster.main PROJECT_ID-CLUSTER_NAME [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#auto-scaling-configuration]
1. Auto-Scaling Causes Perpetual Drift
- Fix (v2 preferred): use_effective_fields = true [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#1-auto-scaling-causes-perpetual-drift]
2. replication_specs Ordering Causes Forced Replace
- Fix: Order region_configs by descending priority (7 first, 1 last). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#2-replication_specs-ordering-causes-forced-replace]
3. Network Container CIDR Cannot Be Changed
- Atlas locks the CIDR once M10+ clusters or peering connections exist. Plan ahead with /21 or larger. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#3-network-container-cidr-cannot-be-changed]
4. Provider v2 Removed Resources Cause Init Errors
- Migrate all removed resources before bumping the provider version constraint. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#4-provider-v2-removed-resources-cause-init-errors]
8. X.509 Authentication Deprecation
- Problem: mongodbatlas_x509_authentication_database_user removed in v2.x. Fix: Use mongodbatlas_database_user with x509_type = "MANAGED" or "CUSTOMER". [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#8-x509-authentication-deprecation]
10. Provider v1 → v2 Migration Guide
- Key removals: mongodbatlas_cluster, mongodbatlas_serverless_instance, mongodbatlas_teams, mongodbatlas_org_invitation, mongodbatlas_project_invitation, mongodbatlas_data_lake_pipeline. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#10-provider-v1-v2-migration-guide]
- Migration order: migrate resources first on v1.x → verify clean plan → bump version → init -upgrade → plan → apply. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-terraform/#10-provider-v1-v2-migration-guide]
Where this helps
- Provisioning Atlas clusters, networking, and database users declaratively as part of an existing Terraform-based infrastructure workflow. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Migrating an existing Atlas Terraform configuration from provider v1.x (mongodbatlas_cluster) to v2.x (mongodbatlas_advanced_cluster) without unplanned resource replacement. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Diagnosing perpetual drift on an advanced_cluster resource caused by autoscaling, or a forced replace caused by replication_specs ordering. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Setting up authentication for CI/CD automation, such as Terraform Cloud or Atlantis, against the Atlas Admin API without hardcoding credentials. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Migrate an existing Atlas Terraform config from mongodbatlas_cluster to mongodbatlas_advanced_cluster, adding use_effective_fields = true to eliminate lifecycle.ignore_changes drift workarounds. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a Terraform module for Atlas cluster provisioning authenticated via a Service Account (OAuth 2.0 client credentials) instead of legacy Programmatic API Keys, sourcing the secret from a vault rather than the .tf files. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Reproduce and fix the replication_specs forced-replace issue by reordering region_configs by descending priority. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Design a Network Container CIDR plan, using /21 or larger, up front, since the CIDR can't be changed once M10+ clusters or peering connections exist against it. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Hardcoding Atlas API keys directly in .tf files instead of using HashiCorp Vault, AWS Secrets Manager, or Terraform Cloud workspace variables. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Leaving the provider version unconstrained instead of pinning to a minor version range, such as ~> 2.7, risking an unplanned breaking upgrade on the next init. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Using 0.0.0.0/0 in the API key IP access list for a production configuration instead of scoping it to the actual CI/CD egress IP range. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Bumping the provider major version constraint before migrating every resource the new version removed, which causes init errors rather than a clean upgrade. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- mongodbatlas_x509_authentication_database_user was removed in provider v2.x — X.509 users now have to be managed through mongodbatlas_database_user with x509_type instead. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Several resources were removed outright in the v1-to-v2 migration, including mongodbatlas_cluster, mongodbatlas_serverless_instance, mongodbatlas_teams, mongodbatlas_org_invitation, mongodbatlas_project_invitation, and mongodbatlas_data_lake_pipeline, so a naive version bump on an existing config will fail to apply. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Atlas locks a Network Container's CIDR block once any M10+ cluster or peering connection exists against it, making an undersized initial CIDR a persistent constraint rather than something fixable later. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Auto-scaling configuration is a common source of perpetual drift unless use_effective_fields = true is set, which isn't obvious from the resource schema alone. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Atlas Cluster IaC (frontier, viability 3.13 / 5, below research gate)
- Atlas Networking IaC (frontier, viability 4.08 / 5)
- Atlas RBAC IaC (frontier, viability 3.77 / 5)
- Atlas Encryption IaC (frontier, viability 3.58 / 5)
- Atlas Backup IaC (frontier, viability 3.85 / 5)
- Terraform Provider v2 Migration (frontier, viability 4.08 / 5)
Frontier under this node: Atlas Backup IaC (3.85), Atlas Cluster IaC (3.13), Atlas Encryption IaC (3.58), Atlas Networking IaC (4.08), Atlas RBAC IaC (3.77), Terraform Provider v2 Migration (4.08)