使用 Terraform 模块部署MongoDB Atlas

本指南将引导您使用官方 Terraform MongoDB Atlas模块部署企业级MongoDB Atlas环境，该模块有助于使用 Terraform 从零部署到完整的Atlas部署。

每个模块都是可重用的构建区块，用于预配Atlas资源以及与云提供商进行安全私有连接所需的依赖项。

本指南提供了在 AWS、 Azure或 Google Cloud 中部署以下资源的示例：

一个Atlas项目和分片集群。
具有 PrivateLink 连接的云提供商网络。
备份导出到云存储。
可选的验证虚拟机，用于确认端到端连接（目前在 Google Cloud 中不可用。虚拟机将在未来的更新中可用）。

注意

本指南中的示例默认创建所有必需的云提供商资源。如果您需要使用预先存在的资源，请参阅与您的云提供商对应的“自带资源”部分：

先决条件

在开始本教程之前，请确保您具备以下先决条件：

所需工具

您需要以下工具来完成本指南中概述的进程：

Terraform（从 v.1 9开始）
mongosh （仅验证步骤需要。部署验证虚拟机时，默认安装mongosh ）

身份验证和档案

MongoDB Atlas

本指南使用Atlas 服务帐户进行身份验证。服务帐户是编程访问权限的推荐身份验证方法。

登录或创建您的MongoDB Atlas帐户。
将服务帐户凭证设置为环境变量：
```
export MONGODB_ATLAS_CLIENT_ID="<your-client-id>"
export MONGODB_ATLAS_CLIENT_SECRET="<your-client-secret>"
```
注意
服务帐户是使用 Terraform 进行编程访问权限时推荐的身份验证方法。有关设置服务帐户的更多信息，请参阅向组织授予编程访问权限。

云服务提供商

使用以下方法之一配置 AWS凭证：

环境变量：
```
export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
```
AWS CLI配置文件：运行 aws configure以存储AWS CLI 的凭证。
IAM角色：在 AWS 中运行时，将 IAM角色附加到具有适当权限的实例或任务。
注意
有关更多信息，请参阅 AWS IAM 身份验证。

使用以下方法之一配置Azure凭证：

Azure CLI：
```
az login
```
服务主体环境变量：
```
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>"
```

注意

有关详细信息，请参阅设置和管理Azure服务主体访问权限。

使用以下方法之一配置 Google Cloud凭证：

应用程序默认凭证：
```
gcloud auth application-default login
```
服务帐户密钥文件：
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
```
服务帐户模拟：将service_account_email 中的terraform.tfvars 变量设置为要模拟的服务帐户的电子邮件。

注意

有关更多信息，请参阅管理GCP访问。

步骤

获取示例配置文件

从Atlas示例存储库下载您的云提供商的完整示例，然后导航到示例目录。

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

配置部署变量。

复制示例terraform.tfvars文件并填写您的值：

cp terraform.tfvars.example terraform.tfvars

下表描述了所需的变量。有关可用变量的完整列表，请参阅示例目录中与您的云提供商对应的 variables.tf文件。

公用变量

变量	说明
`atlas_org_id`	您的MongoDB Atlas组织ID。要找到它，请转到Atlas用户界面中的 Organization > Settings 。
`atlas_project_name`	新Atlas项目的名称。
`atlas_cluster_name`	Atlas 集群的名称。
`regions`	部署集群和 PrivateLink 端点的区域列表。请参阅下面特定于云提供商的详细信息。

特定于云提供商的变量

变量	说明
`aws_region`	提供商操作的主节点 (primary node in the replica set)AWS地区（示例`us-east-1` ）。
`regions[].name`	集群分片的Atlas地区名称（示例`US_EAST_1` ）。有关所有支持的值，请参阅 Cloud Providers and Regions（云提供商和地区）。
`regions[].vpc_id`	该地区中现有VPC的ID 。必须在VPC上启用 DNS 主机名和 DNS 解析。
`regions[].subnet_ids`	VPC内不同可用区中的至少两个私有子网 ID 的列表，用于 PrivateLink 端点放置。

以下示例显示了terraform.tfvars 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>"]
  }
]

变量	说明
`azure_resource_group_name`	在其中创建私有端点、备份存储和可选验证虚拟机的Azure资源组。资源组必须已存在。
`azure_subscription_id`	您的Azure订阅ID 。如果省略，该模块将使用Azure凭证中的默认订阅。
`regions[].name`	集群分片的Atlas地区名称（示例`US_EAST_2` ）。有关所有支持的值，请参阅 Cloud Providers and Regions（云提供商和地区）。
`regions[].azure_location`	此地区的Azure位置（示例 `eastus2`）。仅第一个地区条目需要。
`regions[].subnet_id`	创建私有端点和验证虚拟机的 Azure子网ID 。

terraform.tfvars以下示例显示了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>"
  }
]

变量	说明
`gcp_project_id`	您的 Google Cloud项目ID。
`regions[].name`	Atlas格式（示例`US_EAST_4` ）或 Google Cloud 格式（示例`us-east4` ）的地区名称。该模块在内部对两种格式进行规范化。有关所有支持的值，请参阅 Cloud Providers and Regions（云提供商和地区）。
`regions[].subnetwork`	在其中创建 PSC 转发规则的子网 `self_link`（示例`https://www.googleapis.com/compute/v1/projects/<PROJECT>/regions/<REGION>/subnetworks/<NAME>`）。 VPC网络是自动从子网派生的。

以下示例显示了 Google Cloud 的最小 terraform.tfvars：

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>"
  }
]

初始化和部署

运行以下 Terraform 命令以初始化工作目录并部署基础架构：

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

terraform init 下载所需的提供商和模块插件。 terraform plan 预览将创建的资源。申请前请仔细查看该计划。

terraform apply 完成后，将在您的帐户中预配以下资源：

MongoDB Atlas：组织访问权限、新项目和多区域分片集群。
AWS IAM 角色： Atlas为与您的 AWS 帐户进行交互以获取云提供商访问权限而假定的角色。
AWS VPC端点：每个地区一个VPC端点，连接到Atlas PrivateLink 服务以实现私有、安全的连接。
AWS S3 存储桶：用于Atlas备份导出的存储桶。
验证虚拟机（可选，默认默认）：第一个区域子网中的 EC2 实例，用于验证通过 PrivateLink 的Atlas连接。

MongoDB Atlas：组织访问权限、新项目和多区域分片集群。
Azure服务主体： Atlas用于与Azure订阅交互的Azure AD 服务主体。
Azure私有端点：每个地区一个私有端点，连接到Atlas PrivateLink 服务以实现私有、安全的连接。
Azure存储帐户：用于Atlas备份导出的存储帐户和 blob容器。
验证虚拟机（可选，默认默认）：第一个区域子网中的Linux虚拟机，用于验证通过 PrivateLink 的Atlas连接。

MongoDB Atlas：组织访问权限、新项目和多区域分片集群。
GCP Access：经授权可与 Google Cloud项目交互的Atlas服务帐号。
PSC 转发规则：每个地区一个 Google Cloud 转发规则和计算解决，通过 Private Service Connect (PSC) 连接到Atlas PrivateLink 服务，实现私有、安全的连接。
GCP存储桶：用于Atlas备份导出的 Google Cloud Storage 存储桶。

验证部署

您可以使用该示例为您创建的虚拟机 (VM) 来验证部署，也可以使用 PrivateLink连接字符串直接与 mongosh 连接来验证部署。

连接虚拟机并进行测试

如果部署了验证虚拟机（默认启用），则可以使用它来验证专用网络内的Atlas连接。虚拟机已预安装 mongosh 并预配置连接字符串。

请注意实例ID和访问权限命令的 validation_vm 输出：
```
terraform output validation_vm
```
通过 AWS Systems 经理 (SSM) 会话经理连接（默认，无需 SSH）：
```
aws ssm start-session --target <instance-id>
```
或者，如果设立了validation_vm_create_ec2_instance_connect_endpoint = true ，则通过 EC2 Instance Connect 进行连接：
```
aws ec2-instance-connect ssh --instance-id <instance-id> --os-user ubuntu
```
在虚拟机上运行验证脚本以测试连接：
```
./validate-atlas
```
该脚本确认 mongosh 可以连接，并对集群运行增删改查操作。

请注意 VM name 和用户名的 validation_vm 输出：
```
terraform output validation_vm
```
Retrieve the VM password:
```
terraform output -raw validation_vm_password
```
通过Azure门户中的Azure串行控制台进行连接；或者，如果您通过 提供了 SSH 密钥，则通过Azure Bastionvalidation_vm_ssh_key 进行连接。
在虚拟机上运行验证脚本以测试连接：
```
./validate-atlas
```
该脚本确认 mongosh 可以连接，并对集群运行增删改查操作。

Google Cloud示例目前不包含验证虚拟机。使用下面的 mongosh 连接方法验证您的部署。要使此方法成功，您必须从其中一个 Google Cloud 子网运行mongosh。

连接并测试 mongosh

您还可以从任何托管访问权限您的专用网络的主机测试连接。

检索连接字符串。
部署完成后，从 Terraform 输出中检索PrivateLink连接字符串：
```
terraform output connection_string
```
连接字符串使用私有端点 SRV 格式，并通过 PrivateLink 连接路由流量。
运行以下命令，将 <connection-string> 替换为 terraform output connection_string 命令中的值：
```
mongosh "<connection-string>"
```
连接后，运行以下命令以写入和检索测试文档：
```
db.test.insertOne({ msg: "Hello Atlas" })
db.test.findOne()
```

成功的响应确认您的集群可访问并接受读取和写入操作。

（可选）清理资源

要拆除此部署提供的所有资源并避免不必要的费用，运行：

terraform destroy -var-file terraform.tfvars

警告

terraform destroy 永久删除此配置托管的所有资源，包括Atlas 集群及其数据。在运行此命令之前，请备份要保留的所有数据。

其他资源

Atlas示例存储库：适用于 AWS、 Azure和 Google Cloud 的完整且可运行的 Terraform 示例。
Terraform- MongoDB Atlas模块：包含所有可用模块的官方 Terraform 模块注册表命名空间。
Atlas Terraform Provider：完整的提供商文档。
Terraform 入门：使用 Terraform预配基本Atlas 集群的快速入门指南。
Atlas组织、项目和集群指南： Atlas架构中心关于设计Atlas基础架构的指导。

后退

开始使用 Terraform

来年

Amazon Web Services上的GraphQL API