MongoDB Atlas Terraform Provider

Parent: MongoDB Atlas · researched 2026-05-28T18:39:24.672Z· 18 sources · 10 concepts · skill mongodb-atlas-terraform

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

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. [source]
Registry: registry.terraform.io/providers/mongodb/mongodbatlas [source]
GitHub: github.com/mongodb/terraform-provider-mongodbatlas [source]

When to Use This Skill

Provisioning Atlas clusters, networking, or users via Terraform [source]
Migrating from mongodbatlas_cluster (v1 legacy) to mongodbatlas_advanced_cluster (v2 preferred) [source]
Debugging provider v1 → v2 breaking changes and upgrade errors [source]
Setting up Private Link, VPC peering, or network containers [source]
Configuring encryption at rest (AWS KMS, Azure Key Vault, GCP KMS) [source]
Writing search index resources or search node deployments [source]
Designing module interfaces for reusable Atlas IaC patterns [source]
Configuring Atlantis or Terraform Cloud for Atlas API key management [source]

When NOT to Use This Skill

Using Pulumi for MongoDB Atlas (use the Pulumi mongodbatlas package instead) [source]
Using Crossplane for MongoDB Atlas (use the Crossplane MongoDB Atlas provider) [source]
Using the Atlas Kubernetes Operator (mongodbatlas-kubernetes-operator skill covers that) [source]
CloudFormation / CDK stacks for Atlas resources [source]

Required Providers Block

Pin a specific minor version to avoid unplanned upgrades: [source]
For v1.x users not yet ready to migrate: [source]

Authentication Methods

Method 1 - Environment Variables (recommended for CI/CD): [source]
Provider block with no credentials (reads from env): [source]
Method 2 - Explicit in provider block (use only with secrets injection): [source]
Never hard-code keys in .tf files. Use HashiCorp Vault, AWS Secrets Manager, or TFC workspace variables. [source]
Method 3 - Service Account (new in v2, recommended for production): [source]
Atlas supports Service Accounts with OAuth 2.0 client credentials. The provider reads MONGODB_ATLAS_CLIENT_ID and MONGODB_ATLAS_CLIENT_SECRET environment variables: [source]
Note - AWS IAM Assumed Role (for resource-level cloud access, not provider auth): [source]
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. [source]

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

Version Pinning Best Practices

Use ~> 2.7 (allows patch updates within 2.x, blocks 3.x) [source]
Lock to an exact version in production, allow patch updates (~> 2.7) in dev/staging [source]
Run terraform init -upgrade explicitly when bumping the version constraint [source]
Check the CHANGELOG before any minor version bump for deprecation notices [source]

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). [source]

Auto-Scaling Configuration

Use use_effective_fields = true to eliminate lifecycle.ignore_changes blocks: [source]
Import: terraform import mongodbatlas_advanced_cluster.main PROJECT_ID-CLUSTER_NAME [source]

1. Auto-Scaling Causes Perpetual Drift

Fix (v2 preferred): use_effective_fields = true [source]

2. replication_specs Ordering Causes Forced Replace

Fix: Order region_configs by descending priority (7 first, 1 last). [source]

3. Network Container CIDR Cannot Be Changed

Atlas locks the CIDR once M10+ clusters or peering connections exist. Plan ahead with /21 or larger. [source]

4. Provider v2 Removed Resources Cause Init Errors

Migrate all removed resources before bumping the provider version constraint. [source]

8. X.509 Authentication Deprecation

Problem: mongodbatlas_x509_authentication_database_user removed in v2.x. [source]
Fix: Use mongodbatlas_database_user with x509_type = "MANAGED" or "CUSTOMER". [source]

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. [source]
Migration order: migrate resources first on v1.x → verify clean plan → bump version → init -upgrade → plan → apply. [source]

Children

Atlas Cluster IaC (frontier)
Atlas Networking IaC (frontier)
Atlas RBAC IaC (frontier)
Atlas Encryption IaC (frontier)
Atlas Backup IaC (frontier)
Terraform Provider v2 Migration (frontier)

Frontier under this node: Atlas Backup IaC, Atlas Cluster IaC, Atlas Encryption IaC, Atlas Networking IaC, Atlas RBAC IaC, Terraform Provider v2 Migration

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