Implantar MongoDB Atlas com módulos Terraform

Este guia orienta você na implantação de um ambiente MongoDB Atlas pronto para empresas usando os módulos oficiais do Terraform MongoDB Atlas, que facilitam a saída de zero a uma implantação completa do Atlas usando o Terraform.

Cada módulo é um bloco de construção reutilizável que realiza o provisionamento dos recursos do Atlas juntamente com as dependências necessárias para conectividade segura e privada com provedores de nuvem.

Este guia fornece exemplos para implantar os seguintes recursos no AWS, Azure ou Google Cloud:

Um projeto Atlas e um cluster fragmentado.
Rede de provedor de nuvem com conectividade PrivateLink.
Exportação de backup para armazenamento na nuvem.
Uma máquina virtual de validação opcional para confirmar a conectividade de ponta a ponta (não disponível no momento no Google Cloud. Uma máquina virtual estará disponível em uma atualização futura).

Observação

Os exemplos neste guia criam todos os recursos do provedor de nuvem necessários por padrão. Se você precisar usar recursos preexistentes, consulte as seções Traga seus próprios recursos que correspondem ao seu provedor de nuvem:

Pré-requisitos

Certifique-se de ter os seguintes pré-requisitos antes de iniciar este tutorial:

Ferramentas necessárias

Você precisa das seguintes ferramentas para passar pelo processo descrito neste guia:

Terraform (Do v1.9 em diante)
mongosh (Only required for validation steps. When deploying the validation VM, mongosh is installed by default)

Autenticação e credenciais

MongoDB Atlas

Este guia utiliza uma Conta de Serviço do Atlas para autenticação. As contas de serviço são o método de autenticação recomendado para acesso programático.

Inicie sessão ou crie a sua conta MongoDB Atlas.
Defina as credenciais da sua conta de serviço como variáveis de ambiente:
export MONGODB_ATLAS_CLIENT_ID="<your-client-id>" export MONGODB_ATLAS_CLIENT_SECRET="<your-client-secret>"
Observação
As contas de serviço são o método de autenticação recomendado para acesso programático com o Terraform. Para obter mais informações sobre como configurar contas de serviço, consulte Conceder Acesso Programático a uma Organização.

Provedor de nuvem

Configure suas credenciais da AWS usando um dos seguintes métodos:

Variáveis de ambiente:
export AWS_ACCESS_KEY_ID="<your-access-key-id>" export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
Perfil CLI da AWS: execute aws configure para armazenar credenciais para a CLI da AWS.
Função do IAM: ao executar na AWS, anexe uma função do IAM à sua instância ou tarefa com as permissões apropriadas.

Observação
Para obter mais informações, consulte Autenticação AWS IAM.

Configure suas credenciais do Azure utilizando um dos seguintes métodos:

CLI do Azure:
az login
Variáveis de ambiente do serviço principal:
export ARM_CLIENT_ID="<your-client-id>" export ARM_CLIENT_SECRET="<your-client-secret>" export ARM_SUBSCRIPTION_ID="<your-subscription-id>" export ARM_TENANT_ID="<your-tenant-id>"

Observação

Para obter mais informações, consulte Configurar e gerenciar o Azure Service Principal Access.

Configure suas credenciais do Google Cloud usando um dos seguintes métodos:

Credenciais padrão do aplicativo:
gcloud auth application-default login
Arquivo de chave da conta de serviço:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
Representação da conta de serviço: defina a variável service_account_email em terraform.tfvars para o e-mail da conta de serviço a ser incorporada.

Observação

Para obter mais informações, consulte Gerenciar acesso ao GCP.

Procedimento

Obtenha os arquivos de configuração de exemplo

Baixe o exemplo completo do seu provedor de nuvem no repositório de exemplos do Atlas e navegue até o diretório de exemplo.

git clone https://github.com/terraform-mongodbatlas-modules/atlas-examples.git
cd atlas-examples/aws/atlas-aws-module-complete

git clone https://github.com/terraform-mongodbatlas-modules/atlas-examples.git
cd atlas-examples/azure/atlas-azure-module-complete

git clone https://github.com/terraform-mongodbatlas-modules/atlas-examples.git
cd atlas-examples/gcp/atlas-gcp-module-complete

Configurar variáveis de implantação.

Copie o arquivo de exemplo terraform.tfvars e preencha seus valores:

cp terraform.tfvars.example terraform.tfvars

A tabela a seguir descreve as variáveis necessárias. Para obter uma lista completa das variáveis disponíveis, consulte o arquivo variables.tf no diretório de exemplo que corresponde ao seu provedor de nuvem.

Variáveis comuns

Variável	Descrição
`atlas_org_id`	ID da organização do MongoDB Atlas . Para encontrá-lo, acesse Organization > Settings na IU do Atlas.
`atlas_project_name`	Nome para o novo projeto Atlas .
`atlas_cluster_name`	Nome do Atlas cluster.
`regions`	Lista de regiões onde o cluster e os pontos de extremidade do PrivateLink são implantados. Consulte detalhes específicos do provedor de nuvem abaixo.

Variáveis específicas do fornecedor de nuvem

Variável	Descrição
`aws_region`	A região primária AWS para operações do provedor (por exemplo, `us-east-1`).
`regions[].name`	The Atlas region name for the cluster shard (for example, `US_EAST_1`). For all supported values, see Cloud Providers and Regions.
`regions[].vpc_id`	O ID de uma VPC existente nesta região. Os nomes de host DNS e a resolução DNS devem estar habilitados na VPC.
`regions[].subnet_ids`	Lista de pelo menos duas IDs de sub-rede privada em diferentes zonas de disponibilidade dentro da VPC, usadas para o colocação de pontos de extremidade PrivateLink.

O exemplo a seguir mostra um terraform.tfvars mínimo para AWS:

atlas_org_id       = "<YOUR_ATLAS_ORG_ID>"
atlas_project_name = "my-atlas-project"
atlas_cluster_name = "my-atlas-cluster"
aws_region = "us-east-1"
regions = [
  {
    name       = "US_EAST_1"
    vpc_id     = "<YOUR_VPC_ID>"
    subnet_ids = ["<YOUR_SUBNET_ID_1>", "<YOUR_SUBNET_ID_2>"]
  }
]

Variável	Descrição
`azure_resource_group_name`	Azure Grupo de Recursos onde os private endpoints, o armazenamento de backup e a VM de validação opcional são criados. O grupo de recursos já deve existir.
`azure_subscription_id`	Sua ID de assinatura do Azure. Se omitido, o módulo usa a assinatura padrão de suas credenciais do Azure.
`regions[].name`	The Atlas region name for the cluster shard (for example, `US_EAST_2`). For all supported values, see Cloud Providers and Regions.
`regions[].azure_location`	A localização do Azure para esta região (por exemplo, `eastus2`). Apenas necessário para a primeira entrada da região.
`regions[].subnet_id`	O ID de sub-rede do Azure onde os private endpoints e a VM de validação são criados.

O exemplo a seguir mostra um terraform.tfvars mínimo para o Azure:

atlas_org_id       = "<YOUR_ATLAS_ORG_ID>"
atlas_project_name = "my-atlas-project"
atlas_cluster_name = "my-atlas-cluster"
azure_resource_group_name = "<YOUR_RESOURCE_GROUP>"
regions = [
  {
    name           = "US_EAST_2"
    azure_location = "eastus2"
    subnet_id      = "<YOUR_SUBNET_ID>"
  }
]

Variável	Descrição
`gcp_project_id`	ID do grupo do Google Cloud.
`regions[].name`	O nome da região no formato Atlas (por exemplo, `US_EAST_4`) ou no formato do Google Cloud (por exemplo, `us-east4`). O módulo normaliza ambos os formatos internamente. Para todos os valores suportados, consulte Provedores de nuvem e regiões.
`regions[].subnetwork`	A sub-rede `self_link` onde as regras de encaminhamento do PSC são criadas (por exemplo, `https://www.googleapis.com/compute/v1/projects/<PROJECT>/regions/<REGION>/subnetworks/<NAME>`). A rede VPC é derivada automaticamente da sub-rede.

O exemplo a seguir mostra um terraform.tfvars mínimo para o Google Cloud:

atlas_org_id       = "<YOUR_ATLAS_ORG_ID>"
atlas_project_name = "my-atlas-project"
atlas_cluster_name = "my-atlas-cluster"
gcp_project_id = "<YOUR_GCP_PROJECT_ID>"
regions = [
  {
    name       = "US_EAST_4"
    subnetwork = "<YOUR_SUBNETWORK_SELF_LINK>"
  }
]

Inicializar e implantar

Execute os seguintes comandos Terraform para inicializar o diretório de trabalho e implantar a infraestrutura:

terraform init
terraform plan -var-file terraform.tfvars
terraform apply -var-file terraform.tfvars

terraform init baixa os plug-ins do fornecedor e do módulo necessários. terraform plan visualiza os recursos que serão criados. Revise o plano cuidadosamente antes de aplicá-lo.

Após a conclusão do terraform apply, o provisionamento dos seguintes recursos será realizado na sua conta:

MongoDB Atlas: acesso à organização, um novo projeto e um cluster fragmentado multirregional.
Função AWS IAM: uma função que o Atlas assume para interagir com sua conta AWS para o acesso ao provedor de nuvem.
Pontos de extremidade da AWS VPC: um ponto de extremidade da VPC por região, conectado ao serviço Atlas PrivateLink para conectividade privada e segura.
AWS S3 Bucket: um bucket para as exportações de backup do Atlas.
VM de validação (opcional, ativada por padrão): uma instância do EC2 na sub-rede da primeira região para verificar a conectividade do Atlas por PrivateLink.

Validar a implantação

Você pode validar sua implantação com uma máquina virtual (VM) que o exemplo cria para você ou conectando-se diretamente com o mongosh utilizando a string de conexão PrivateLink.

Conecte-se e teste com uma máquina virtual

Se você implantou a VM de validação (ativada por padrão), poderá usá-la para verificar a conectividade do Atlas a partir da sua rede privada. A VM tem mongosh pré-instalado e a string de conexão pré-configurada.

Observe a saída validation_vm para o ID da instância e os comandos de acesso:
terraform output validation_vm
Conecte-se via AWS Gerente de Sistemas (SSM) Session Manager (padrão, nenhum SSH necessário):
aws ssm start-session --target <instance-id>
Como alternativa, se você definir validation_vm_create_ec2_instance_connect_endpoint = true, conecte-se via EC2 Instância Connect:
aws ec2-instance-connect ssh --instance-id <instance-id> --os-user ubuntu
Execute o script de validação na VM para testar a conectividade:
./validate-atlas
O script confirma que mongosh pode se conectar e executa operações CRUD no cluster.

Observe a saída validation_vm para o nome da VM e o nome de usuário:
terraform output validation_vm
Retrieve the VM password:
terraform output -raw validation_vm_password
Conecte-se através do Azure Serial Console no portal Azure, ou através do Azure Bastion se você forneceu uma chave SSH com validation_vm_ssh_key.
Execute o script de validação na VM para testar a conectividade:
./validate-atlas
O script confirma que mongosh pode se conectar e executa operações CRUD no cluster.

Atualmente, o exemplo do Google Cloud não inclui uma VM de validação. Use o método de conexão mongosh abaixo para verificar sua implantação. Você deve executar mongosh de uma de suas sub-redes do Google Cloud para que este método seja bem-sucedido.

Conecte-se e teste com mongosh

Você também pode testar a conectividade de qualquer hospedar com acesso à sua rede privada.

Recupere a string de conexão.
Após a conclusão da implantação, recupere a string de conexão PrivateLink das saídas do Terraform:
terraform output connection_string
A string de conexão usa o formato SRV de ponto de extremidade privado e roteia o tráfego por meio da conexão PrivateLink.
Execute o seguinte comando, substituindo <connection-string> pelo valor do comando terraform output connection_string:
mongosh "<connection-string>"
Após conectar, execute os seguintes comandos para gravar e recuperar um documento de teste:
db.test.insertOne({ msg: "Hello Atlas" }) db.test.findOne()

Uma resposta bem-sucedida confirma que seu cluster está acessível e aceitando operações de leitura e gravação.

(Opcional) Limpar recursos

Para reduzir todos os recursos provisionados por essa implantação e evitar cobranças indesejadas, execute:

terraform destroy -var-file terraform.tfvars

Aviso

terraform destroy exclui permanentemente todos os recursos gerenciados por esta configuração, incluindo o Atlas cluster e seus dados. Faça backup de todos os dados que deseja manter antes de executar este comando.

Recursos adicionais

Repositório de Exemplos do Atlas: exemplos de Terraform completos e executáveis para AWS, Azure e Google Cloud.
Módulos Terraform- MongoDB Atlas: O namespace oficial do registro do módulo Terraform com todos os módulos disponíveis.
Atlas Provedor Terraform: Documentação completa do provedor.
Introdução ao Terraform: um guia de início rápido para provisionamento de um Atlas cluster básico com o Terraform.
Orientação para organizações, projetos e clusters do Atlas : orientações do Atlas Architecture Center para projetar sua infraestrutura do Atlas .

Voltar

Comece com o Terraform

APIs GraphQL no Amazon Web Services