Como implantar o MongoDB Atlas com o Terraform na AWS
Avalie esse Tutorial
MongoDB Atlas é a plataforma de dados multinuvem que fornece um conjunto integrado de banco de dados e serviços de dados na nuvem. Ajudamos a acelerar e simplificar a forma como você cria aplicativos globais resilientes e de alto desempenho no provedor de nuvem de sua escolha.
O HashiCorp Terraform é uma ferramenta de infraestrutura como código (IaC) que permite definir recursos de nuvem em arquivos de configuração legíveis por humanos que você pode versionar, reutilizar e compartilhar. Por isso, criamos o Terraform MongoDB Atlas Provider que automatiza as implantações de infraestrutura, facilitando o provisionamento, gerenciamento e o controle das configurações do Atlas como código em qualquer um dos três principais provedores de nuvem.
Além disso, as equipes também podem optar por implantar o MongoDB Atlas por meio do MongoDB Atlas CLI (interface da linha de comando), API de administração do Atlas, AWS CloudFormation e, como sempre, com a IU do Atlas (interface de usuário).
Nesta publicação no blog, aprenderemos como implantar o MongoDB Atlas hospedado na AWS usando o Terraform. Além disso, exploraremos como usar pontos de extremidade privados com o AWS Private Link para fornecer maior segurança com conectividade privada para seu MongoDB Atlas cluster sem expor o tráfego para a internet pública.
Criamos este início rápido para usuários novatos sem experiência com MongoDB Atlas, HashiCorp Terraform ou AWS e que procuram configurar seu primeiro ambiente. Sinta-se à vontade para acessar todo o código-fonte descrito abaixo a partir deste repositório do GitHub.
Vamos começar:
Cadastre-se para obter uma conta gratuita do MongoDB Atlas, verifique seu endereço de e-mail e faça login em sua nova conta.

Depois de criar uma conta e fazer login no MongoDB Atlas, você precisará gerar uma chave de API para autenticar o provedor Terraform MongoDB Atlas.
Vá para a parte superior do Atlas, clique no ícone de engrenagem à direita do nome da organização que você criou, clique em Access Manager na barra de menu à esquerda, clique na aba API e, em seguida, clique na caixa verde Criar chave de API.

Insira uma descrição para a chave de API que o ajudará a lembrar para que ela está sendo usada — por exemplo, "Terraform API Key." Em seguida, você selecionará a permissão apropriada para o que deseja realizar com o Terraform. As funções Proprietário da organização e Criador de projeto da organização (consulte as descrições de função abaixo) fornecerão acesso para concluir essa tarefa, mas usando o princípio de privilégio mínimo, vamos selecionar a função Criador de projeto da organização no menu suspenso e clicar em Avançar.
Certifique-se de copiar sua chave privada e armazená-la em um local seguro. Depois de sair desta página, sua chave privada completa não poderá ser acessada.

As chaves de API do MongoDB Atlas têm endpoints específicos que requerem uma lista de acesso de chave de API. A criação de uma lista de acesso de chave de API garante que as chamadas de API sejam originadas de IPs ou faixas CIDR com acesso. Para relembrar, saiba mais sobre redes em nuvem.
Na mesma página, role para baixo e clique em Adicionar entrada da lista de acesso. Se não tiver certeza do endereço IP em que está executando o Terraform (e estiver executando esta etapa nessa máquina), basta clicar em Usar endereço IP atual e Salvar. Outra opção é abrir sua lista de acesso IP a todos, mas isso acarreta um risco potencial significativo. Para fazer isso, você pode adicionar os seguintes dois CIDRs: 0.0.0.0/1 e 128.0.0.0/1. Essas entradas abrirão sua lista de acesso IP para no máximo 4.294.967.296 (ou 2^32) endereços IPv4 e devem ser usadas com cuidado.

Vá para a barra de menu à esquerda e clique em Cobrança e, depois, em Adicionar método de pagamento. Siga as etapas para garantir que haja um método de pagamento válido para sua organização. Observe que ao criar uma camada do cluster gratuita (para sempre) ou M0, você pode pular esta etapa.

Vá para a página oficial de downloads do Terraform do HashiCorp e siga as instruções para configurar o Terraform na plataforma de sua escolha. Para os fins desta demonstração, usaremos um ambiente Ubuntu/Debian.

Precisamos configurar o provedor do MongoDB Atlas usando a chave de API do MongoDB Atlas que você gerou anteriormente (Etapa 2). Armazenaremos esses secrets com segurança como variáveis de ambiente.
Primeiro, vá para a janela do terminal e crie variáveis de ambiente com os comandos abaixo. Isso evita que você tenha que codificar segredos diretamente nos arquivos de configuração do Terraform (o que não é recomendado):
1 export MONGODB_ATLAS_PUBLIC_KEY="<insert your public key here>" 2 export MONGODB_ATLAS_PRIVATE_KEY="<insert your private key here>"
Em seguida, crie em um diretório vazio com um arquivo vazio chamado provider.tf. Aqui inseriremos o seguinte código para definir o provedor Atlas MongoDB. Isso capturará automaticamente a versão mais atual do provedor Terraform MongoDB Atlas.
1 # Define the MongoDB Atlas Provider 2 terraform { 3 required_providers { 4 mongodbatlas = { 5 source = "mongodb/mongodbatlas" 6 } 7 } 8 required_version = ">= 0.13" 9 }
Agora, criaremos um arquivo variables.tf para declarar todas as variáveis do Terraform usadas como parte deste exercício e todas elas são do tipo string. Em seguida, definiremos valores (ou seja, nossos segredos) para cada uma dessas variáveis no arquivo terraform.tfvars. Observe que, como acontece com a maioria dos segredos, a prática recomendada é não carregá-los (ou o próprio arquivo terraform.tfvars) em repositórios públicos.
1 # Atlas Organization ID 2 variable "atlas_org_id" { 3 type = string 4 description = "Atlas Organization ID" 5 } 6 # Atlas Project Name 7 variable "atlas_project_name" { 8 type = string 9 description = "Atlas Project Name" 10 } 11 12 # Atlas Project Environment 13 variable "environment" { 14 type = string 15 description = "The environment to be built" 16 } 17 18 # Cluster Instance Size Name 19 variable "cluster_instance_size_name" { 20 type = string 21 description = "Cluster instance size name" 22 } 23 24 # Cloud Provider to Host Atlas Cluster 25 variable "cloud_provider" { 26 type = string 27 description = "AWS or GCP or Azure" 28 } 29 30 # Atlas Region 31 variable "atlas_region" { 32 type = string 33 description = "Atlas region where resources will be created" 34 } 35 36 # MongoDB Version 37 variable "mongodb_version" { 38 type = string 39 description = "MongoDB Version" 40 } 41 42 # IP Address Access 43 variable "ip_address" { 44 type = string 45 description = "IP address used to access Atlas cluster" 46 }
O exemplo abaixo especifica o uso da versão mais atual do MongoDB (no momento em que este artigo foi escrito), que é a 6.0, uma camada do cluster M10 que é ótima para um ambiente de desenvolvimento robusto e será implantada na AWS na região do Atlas US_WEST_2 . Para obter detalhes específicos sobre todas as opções disponíveis além de M10 e US_WEST_2, consulte a documentação.
1 atlas_org_id = "<UPDATE WITH YOUR ORG ID>" 2 atlas_project_name = "myFirstProject" 3 environment = "dev" 4 cluster_instance_size_name = "M10" 5 cloud_provider = "AWS" 6 atlas_region = "US_WEST_2" 7 mongodb_version = "6.0" 8 ip_address = "<UPDATE WITH YOUR IP>"
Em seguida, crie um arquivo main.tf, que preencheremos juntos para criar os recursos mínimos necessários para criar e acessar seu cluster do Atlas: um projeto MongoDB Atlas (Etapa 8), Usuário/Senha do banco de dados (Etapa 9), lista de acesso IP (Etapa 10) e, é claro, o próprio MongoDB Atlas cluster (Etapa 11). Em seguida, mostraremos como criar Terraform Outputs (Etapa 12) para que você possa acessar seu cluster do Atlas e criar um ponto de extremidade privado com o AWS PrivateLink (Etapa 13). Se você já estiver familiarizado com alguma dessas etapas, fique à vontade para pular.
Observação: à medida que os recursos de infraestrutura forem criados, modificados ou destruídos, vários outros arquivos serão gerados em seu diretório pelo Terraform (por exemplo, o arquivo terraform.tfstate). É uma prática recomendada não modificar esses arquivos adicionais diretamente, a menos que você saiba o que está fazendo.
Os projetos do MongoDB Atlas ajudam a organizar e fornecer controles de acesso granulares aos nossos recursos dentro da organização do MongoDB Atlas. Observe que “Groups" e "Projects" do MongoDB Atlas são termos sinônimos.
Para criar um projeto usando Terraform, precisaremos do ID da organização do MongoDB Atlas com pelo menos a função Organization Project Creator (definida quando criamos as chaves de API do provedor do MongoDB Atlas na Etapa 2).
Para obter essas informações, basta clicar em Configurações na barra de menu à esquerda na IU do Atlas e clicar no ícone de cópia ao lado de ID da organização. Agora você pode colar essas informações como atlas_org_id no seu arquivo terraform.tfvars.

A seguir, no arquivo main.tf, usaremos o recurso mongodbatlas_project do provedor Terraform do MongoDB Atlas para criar nosso projeto. Para fazer isso, basta inserir:
1 # Create a Project 2 resource "mongodbatlas_project" "atlas-project" { 3 org_id = var.atlas_org_id 4 name = var.atlas_project_name 5 }
Para autenticar um cliente no MongoDB, como o MongoDB Shell ou o código do aplicativo usando um driver do MongoDB (oficialmente compatível com Python, Node.js, Go, Java, C#, C++, Rust e vários outros), você deve adicionar um usuário de banco de dados correspondente ao seu projeto MongoDB Atlas. Consulte a documentação para obter mais informações sobre as funções de usuário disponíveis para que você possa personalizar o RBAC (Controle de Acesso Baseado em Função) do usuário de acordo com as necessidades da sua equipe.
Por enquanto, basta inserir o seguinte código como parte das próximas linhas no arquivo main.tf para criar um usuário de banco de dados com uma senha aleatória de 16 caracteres. Isso usará o recurso mongodmatlas_database_user do provedor Terraform MongoDB Atlas. O user_password do banco de dados é um segredo confidencial, portanto, para acessá-lo, você precisará inserir o comando "terraform output -json user_password" na janela do terminal após a conclusão da nossa implantação.
1 # Create a Database User 2 resource "mongodbatlas_database_user" "db-user" { 3 username = "user-1" 4 password = random_password.db-user-password.result 5 project_id = mongodbatlas_project.atlas-project.id 6 auth_database_name = "admin" 7 roles { 8 role_name = "readWrite" 9 database_name = "${var.atlas_project_name}-db" 10 } 11 } 12 13 # Create a Database Password 14 resource "random_password" "db-user-password" { 15 length = 16 16 special = true 17 override_special = "_%@" 18 }
Em seguida, criaremos a lista de acesso IP inserindo o seguinte em seu arquivo main.tf. Certifique-se de procurar o endereço IP (ou intervalo CIDR) da máquina de onde você se conectará ao seu MongoDB Atlas cluster e colá-lo no arquivo terraform.tfvars (conforme mostrado no bloco de código na etapa 7). Isso usará o recurso mongodbatlas_project_ip_access_list do provedor Terraform do MongoDB Atlas.
1 # Create Database IP Access List 2 resource "mongodbatlas_project_ip_access_list" "ip" { 3 project_id = mongodbatlas_project.atlas-project.id 4 ip_address = var.ip_address 5 }
Agora usaremos o recurso mongodbatlas_advanced_cluster para criar um MongoDB Atlas cluster. Com esse recurso, você não só pode criar uma implantação, mas também gerenciá-la durante seu ciclo de vida, dimensionando a computação e o armazenamento de forma independente, habilitando backups em nuvem e criando nós de análise.
Neste exemplo, agrupamos três servidores de banco de dados para criar um conjunto de réplicas com um servidor primário e duas réplicas secundárias duplicando os dados do primário. Essa arquitetura é projetada principalmente com alta disponibilidade em mente e pode lidar automaticamente com o failover se um dos servidores ficar inativo — e se recuperar automaticamente quando ele voltar a ficar online. Chamamos todos esses nós de elegíveis porque uma eleição é realizada entre eles para descobrir qual é primário.
Também definiremos o sinalizador opcional backup_enabled como verdadeiro. Isso proporciona maior resiliência de dados, permitindo o armazenamento de backup localizado usando a funcionalidade nativa de snapshot do provedor de serviços de nuvem do cluster (consulte a documentação).
Por fim, criamos um nó de análise . Os nós de análise são nós somente leitura que podem ser usados exclusivamente para executar queries no banco de dados. Isso significa que essa carga de trabalho de análise é isolada somente nesse nó para que o desempenho operacional não seja impacto. Isso torna os nós de análise ideais para executar queries de análise mais longas e com maior intensidade computacional sem impactar o desempenho do seu conjunto de réplicas (consulte a documentação).
1 # Create an Atlas Advanced Cluster 2 resource "mongodbatlas_advanced_cluster" "atlas-cluster" { 3 project_id = mongodbatlas_project.atlas-project.id 4 name = "${var.atlas_project_name}-${var.environment}-cluster" 5 cluster_type = "REPLICASET" 6 backup_enabled = true 7 mongo_db_major_version = var.mongodb_version 8 replication_specs { 9 region_configs { 10 electable_specs { 11 instance_size = var.cluster_instance_size_name 12 node_count = 3 13 } 14 analytics_specs { 15 instance_size = var.cluster_instance_size_name 16 node_count = 1 17 } 18 priority = 7 19 provider_name = var.cloud_provider 20 region_name = var.atlas_region 21 } 22 } 23 }
Você pode enviar informações de sua configuração do Terraform para a janela do terminal da máquina que executa os comandos do Terraform. Isso pode ser especialmente útil para valores que você não saberá até que os recursos sejam criados, como a senha aleatória do usuário de banco de dados ou a string de conexão para o seu cluster do Atlas. O código abaixo no arquivo main.tf enviará esses valores para a exibição do terminal para você usar após a conclusão do Terraform.
1 # Outputs to Display 2 output "atlas_cluster_connection_string" { value = mongodbatlas_advanced_cluster.atlas-cluster.connection_strings.0.standard_srv } 3 output "ip_access_list" { value = mongodbatlas_project_ip_access_list.ip.ip_address } 4 output "project_name" { value = mongodbatlas_project.atlas-project.name } 5 output "username" { value = mongodbatlas_database_user.db-user.username } 6 output "user_password" { 7 sensitive = true 8 value = mongodbatlas_database_user.db-user.password 9 }
Cada vez mais, vemos nossos clientes quererem que seus dados atravessem apenas redes privadas. Uma das melhores maneiras de se conectar ao Atlas por meio de uma rede privada da AWS é usar o AWS PrivateLink, que estabelece uma conexão unidirecional que preserva o limite de confiança da rede percebido e, ao mesmo tempo, elimina controles de segurança adicionais associados a outras opções, como emparelhamento de VPC (Azure Private Link e GCP Private Service Connect também são compatíveis). Saiba mais sobre o AWS Private Link com o MongoDB Atlas.

Em seguida, vamos ao terminal criar variáveis de ambiente da AWS com os comandos abaixo (semelhante ao que fizemos na Etapa 6 com nossas credenciais do MongoDB Atlas). Use a mesma região acima, mas usaremos a convenção de nomenclatura da AWS, ou seja, "us-west-2".
1 export AWS_ACCESS_KEY_ID="<INSERT YOUR KEY HERE>" 2 export AWS_SECRET_ACCESS_KEY="<INSERT YOUR KEY HERE>" 3 export AWS_DEFAULT_REGION="<INSERT AWS REGION HERE>"
Em seguida, adicionamos o provedor AWS ao arquivo provider.tf. Isso nos permitirá agora implantar recursos da AWS do provedor Terraform da AWS, além dos recursos do MongoDB Atlas do provedor Terraform do MongoDB Atlas diretamente dos mesmos arquivos de configuração do Terraform.
1 # Define the MongoDB Atlas and AWS Providers 2 terraform { 3 required_providers { 4 mongodbatlas = { 5 source = "mongodb/mongodbatlas" 6 } 7 aws = { 8 source = "hashicorp/aws" 9 } 10 } 11 required_version = ">= 0.13" 12 }
Agora adicionamos uma nova entrada em nossos arquivos variáveis.tf e terraform.tfvars para a região AWS desejada. Como mencionado anteriormente, usaremos "us-west-2", que é a região da AWS em Oregon, EUA.
variables.tf
1 # AWS Region 2 variable "aws_region" { 3 type = string 4 description = "AWS Region" 5 }
terraform.tfvars
1 aws_region = "us-west-2"
Em seguida, criamos mais dois arquivos para cada um dos novos tipos de recursos a serem implantados: aws-vpc.tf para criar uma configuração de rede completa no lado da AWS e atlas-pl.tf para criar o ponto de extremidade da VPC da Amazon e o ponto de extremidade do MongoDB Atlas do PrivateLink. Em seu ambiente, você já pode ter uma rede AWS criada. Em caso afirmativo, você desejará incluir os valores corretos no arquivo atlas-pl.tf e não precisará do arquivo aws-vpc.tf. Para começar rapidamente, simplesmente os clonaremos com git de nosso repositório.
Depois disso, usaremos uma fonte de dados Terraform e aguardaremos até que a criação do PrivateLink seja concluída para que possamos obter a nova string de conexão para a conexão do PrivateLink. No main.tf, basta adicionar o seguinte:
1 data "mongodbatlas_advanced_cluster" "atlas-cluser" { 2 project_id = mongodbatlas_project.atlas-project.id 3 name = mongodbatlas_advanced_cluster.atlas-cluster.name 4 depends_on = [mongodbatlas_privatelink_endpoint_service.atlaseplink] 5 }
Por último, permanecendo no arquivo main.tf, adicionamos o trecho de código de saída adicional abaixo para exibir a string de conexão compatível com endpoint privado ao terminal:
1 output "privatelink_connection_string" { 2 value = lookup(mongodbatlas_advanced_cluster.atlas-cluster.connection_strings[0].aws_private_link_srv, aws_vpc_endpoint.ptfe_service.id) 3 }
Agora estamos todos prontos para começar a criar nossa primeira implantação do MongoDB Atlas!
Abra o console do terminal e digite o seguinte comando: terraform init para inicializar o Terraform. Isso fará o download e instalará os provedores Terraform AWS e MongoDB Atlas (se você ainda não tiver feito isso).

Em seguida, executaremos o comando terraform plan. Isso produzirá a saída do que o Terraform planeja fazer, como criação, alterações ou destruição de recursos. Se a saída não for o que você espera, é provável que haja um problema nos arquivos de configuração do Terraform.

Em seguida, use o comando terraform apply para implantar a infraestrutura. Se tudo parecer bem, insira sim para aprovar a criação do Terraform.

Sucesso!

Observe que novos recursos da AWS e do MongoDB Atlas podem levar cerca de 15 minutos para serem provisionados, e o provedor continuará fornecendo uma atualização de status até que ela seja concluída. Você também pode verificar o progresso por meio da IU do Atlas e do Console de gerenciamento da AWS.
A string de conexão mostrada na saída pode ser usada para acessar (incluindo a execução de operações CRUD) em seu MongoDB database por meio do MongoDB Shell, da GUI do MongoDB Compass e do Data Explorer na IU (conforme mostrado abaixo). Saiba mais sobre como interagir com dados no MongoDB Atlas com a linguagem de query do MongoDB (MQL). Aproveito sempre o Guia rápido de MongoDB para consultar rapidamente os principais comandos.
Por último, como lembrete, o banco de dados user_password é um secret confidencial, portanto, para acessá-lo, você precisará inserir o comando “terraform output -json user_password” na janela do seu terminal para revelá-lo.


Explore ambientes mais complexos (incluindo exemplos de código para a implantação de MongoDB Atlas Clusters de outros fornecedores de nuvem) que você pode encontrar em nossos exemplos de repositórios públicos. Quando estiver pronto para excluir toda a infraestrutura criada, você pode aproveitar o comando terraform destroy.
Aqui, os recursos que criamos anteriormente serão todos encerrados. Se tudo parecer correto, insira sim:

Depois de alguns minutos, estamos de volta a uma tela inicial em branco em nossos ambientes MongoDB Atlas e AWS. Tenha cuidado ao usar o comando terraform destroy em qualquer tipo de ambiente de produção.

O provedor do MongoDB Atlas do HashiCorp Terraform é um projeto de código aberto licenciado sob a Licença Pública Mozilla 2.0 e agradecemos as contribuições da comunidade. Para saber mais, consulte nossas diretrizes de contribuição. Como sempre, entre em contato conosco caso tenha qualquer problema.
Aproveite o Terraform com o MongoDB Atlas na AWS!
Relacionado
Tutorial
Pesquisando sua localização com Atlas Search e operadores geoespaciais
Mar 21, 2025 | 9 min read
Tutorial
Criação de um agente de AI aprimorado para memória com o laudo do Aconnection no Amazon Cama do MongoDB Atlas
Oct 29, 2024 | 8 min read