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 Terraform do MongoDB Atlas, que facilitam a passagem de zero a uma implantação completa do Atlas usando 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 (Só necessário para etapas de validação. Ao implantar a VM de validação, o mongosh é instalado por padrão)

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, vá para 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 principal região AWS para operações de provedor (por exemplo, `us-east-1`).
`regions[].name`	O nome de região do Atlas para o fragmento do cluster (por exemplo, `US_EAST_1`). Para todos os valores suportados, consulte Provedores de nuvem e regiões.
`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 pontos de extremidade privados, 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`	O nome de região do Atlas para o fragmento do cluster (por exemplo, `US_EAST_2`). Para todos os valores suportados, consulte Provedores de nuvem e regiões.
`regions[].azure_location`	A localização do Azure para esta região (por exemplo, `eastus2`). Necessário apenas para a primeira entrada de região.
`regions[].subnet_id`	O ID de sub-rede do Azure onde os pontos de extremidade privados e a VM de validação são criados.

O exemplo a seguir mostra um terraform.tfvars mínimo para 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.

MongoDB Atlas: acesso à organização, um novo projeto e um cluster fragmentado multirregional.
Azure Service Principal: um Azure AD Service Principal que o Atlas usa para realizar a interação com sua assinatura do Azure.
Azure pontos de extremidade privados: um ponto de extremidade privado por região, conectado ao serviço Atlas PrivateLink para conectividade privada e segura.
Conta de Armazenamento Azure: uma conta de armazenamento e um contêiner de blob para exportações de backup do Atlas.
VM de validação (opcional, ativada por padrão): uma VM Linux na sub-rede da primeira região para verificar a conectividade do Atlas por PrivateLink.

MongoDB Atlas: acesso à organização, um novo projeto e um cluster fragmentado multirregional.
GCP Access: uma conta de serviço do Atlas autorizada para interação com seu projeto do Google Cloud.
Regras de encaminhamento do PSC: uma regra de encaminhamento do Google Cloud e um endereço de computação por região, conectados ao serviço Atlas PrivateLink via Private Service Connect (PSC) para conectividade privada e segura.
Bucket de armazenamento GCP: um bucket de armazenamento do Google Cloud para exportações de backup do Atlas .

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 por meio do Console serial do Azure no portal do Azure ou por meio 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