Implementar MongoDB Atlas con módulos de Terraform

Esta guía te lleva paso a paso para implementar un entorno de MongoDB Atlas listo para empresas utilizando el Módulos de MongoDB Atlas para Terraform, los cuales facilitan el paso de cero a una completa implementación en Atlas utilizando Terraform.

Cada módulo es un bloque de construcción reutilizable que aprovisiona recursos de Atlas junto con las dependencias necesarias para una conectividad segura y privada con los proveedores de la nube.

Esta guía proporciona ejemplos para implementar los siguientes recursos en AWS, Azure o Google Cloud:

Un proyecto Atlas y un clúster particionado.
Red de proveedor de nube con conectividad PrivateLink.
Exportar copia de seguridad a almacenamiento en la nube.
Una máquina virtual de validación opcional para confirmar la conectividad de extremo a extremo (actualmente no disponible en Google Cloud). Una máquina virtual estará disponible en una actualización futura).

Nota

Los ejemplos de esta guía crean por defecto todos los recursos necesarios del proveedor de nube. Si requieres utilizar recursos preexistentes, consulta las secciones de Trae tus propios recursos que correspondan a tu proveedor de nube:

Requisitos previos

Asegúrate de tener los siguientes requisitos previos antes de comenzar este tutorial:

Herramientas requeridas

Necesitas las siguientes herramientas para seguir el proceso descrito en esta guía:

Terraform (Desde v1.9 en adelante)
mongosh (Sólo requerido para los pasos de validación. Al implementar la máquina virtual de validación, mongosh está instalado por defecto)

Autenticación y credenciales

MongoDB Atlas

Esta guía utiliza un Atlas Cuenta de servicio para la autenticación. Las cuentas de servicio son el método de autenticación recomendado para el acceso programático.

Inicia sesión o crea tu cuenta de MongoDB Atlas.
Establezca sus credenciales de Cuenta de Servicio como variables de entorno:
```
export MONGODB_ATLAS_CLIENT_ID="<your-client-id>"
export MONGODB_ATLAS_CLIENT_SECRET="<your-client-secret>"
```
Nota
Las cuentas de servicio son el método de autenticación recomendado para el acceso programático con Terraform. Para obtener más información sobre cómo configurar las cuentas de servicio, consulte Conceder acceso programático a una organización.

Proveedor de nube

Configura tus credenciales de AWS utilizando uno de los siguientes métodos:

Variables de entorno:
```
export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
```
Perfil de AWS CLI: Ejecute aws configure para almacenar credenciales para el AWS CLI.
Rol de IAM: Cuando se ejecuta en AWS, se debe adjuntar un rol IAM a la instancia o tarea con los permisos adecuados.
Nota
Para obtener más información, consulte Autenticación de AWS IAM.

Configura tus credenciales de Azure utilizando uno de los siguientes métodos:

Azure CLI:
```
az login
```
Variables de entorno de Service 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>"
```

Nota

Para obtener más información, consulte Configurar y administrar el acceso de Azure Service Principal.

Configura tus credenciales de Google Cloud utilizando uno de los siguientes métodos:

Credenciales por defecto de la aplicación:
```
gcloud auth application-default login
```
Archivo clave de cuenta de servicio:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
```
Suplantación de cuenta de servicio: Configure la variable service_account_email en terraform.tfvars con el correo electrónico de la cuenta de servicio a suplantar.

Nota

Para obtener más información, consulta Gestionar el acceso a GCP.

Procedimiento

Obtenga los archivos de configuración de ejemplo

Descargue el ejemplo completo para su proveedor de nube del Repositorio de ejemplos de Atlas y navegue al directorio del ejemplo.

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

Configuración de variables de implementación.

Copia el archivo de ejemplo terraform.tfvars y rellena tus propios valores:

cp terraform.tfvars.example terraform.tfvars

La siguiente tabla describe las variables requeridas. Para obtener una lista completa de las variables disponibles, consulta el archivo variables.tf en el directorio de ejemplo que corresponde a tu proveedor de nube.

Variables comunes

Variable	Descripción
`atlas_org_id`	El Identificador de la Organización de MongoDB Atlas. Para encontrarlo, dirígete a Organization > Settings en la Interfaz de Usuario de Atlas.
`atlas_project_name`	Nombre para el nuevo proyecto Atlas.
`atlas_cluster_name`	Nombre para el clúster Atlas.
`regions`	Lista de regiones donde se implementan el clúster y los endpoints de PrivateLink. Consulte los detalles específicos del proveedor de nube a continuación.

Variables específicas del proveedor de nube

Variable	Descripción
`aws_region`	La región principal de AWS para las operaciones del proveedor (por ejemplo, `us-east-1`).
`regions[].name`	El nombre de la región de Atlas para la partición del clúster (por ejemplo, `US_EAST_1`). Para conocer todos los valores compatibles, consulte Proveedores de Nube y Regiones.
`regions[].vpc_id`	El ID de una VPC existente en esta región. Los nombres de host de DNS y la resolución de DNS deben estar habilitados en la VPC.
`regions[].subnet_ids`	Lista de al menos dos IDs de subredes privadas en diferentes Zonas de Disponibilidad dentro de la VPC, utilizada para la ubicación del punto final de PrivateLink.

El siguiente ejemplo muestra un mínimo terraform.tfvars 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>"]
  }
]

Variable	Descripción
`azure_resource_group_name`	Azure Grupo de recursos donde se crean los nodos privados, el almacenamiento de copia de seguridad y la VM de validación opcional. El grupo de recursos debe existir previamente.
`azure_subscription_id`	Su ID de suscripción de Azure. Si se omite, el módulo utiliza la suscripción por defecto de tus credenciales de Azure.
`regions[].name`	El nombre de la región de Atlas para la partición del clúster (por ejemplo, `US_EAST_2`). Para conocer todos los valores compatibles, consulte Proveedores de Nube y Regiones.
`regions[].azure_location`	La ubicación de Azure para esta región (por ejemplo, `eastus2`). Solo se requiere para la primera entrada de la región.
`regions[].subnet_id`	El ID de subred Azure donde se crean los nodos privados y la máquina virtual de validación.

El siguiente ejemplo muestra un mínimo terraform.tfvars 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>"
  }
]

Variable	Descripción
`gcp_project_id`	Tu ID del grupo de Google Cloud.
`regions[].name`	El nombre de la región en formato Atlas (por ejemplo, `US_EAST_4`) o Google Cloud (por ejemplo, `us-east4`). El módulo normaliza internamente ambos formatos. Para todos los valores admitidos, consulte Proveedores de nube y regiones.
`regions[].subnetwork`	La subred `self_link` donde se crean las reglas de reenvío de PSC (por ejemplo, `https://www.googleapis.com/compute/v1/projects/<PROJECT>/regions/<REGION>/subnetworks/<NAME>`). La red de VPC se deriva automáticamente de la subred.

El siguiente ejemplo muestra un terraform.tfvars mínimo para 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>"
  }
]

Inicializa e implementa

Ejecute los siguientes comandos de Terraform para inicializar el directorio de trabajo e implementar la infraestructura:

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

terraform init descarga los plugins de proveedor y módulo necesarios. terraform plan muestra una vista previa de los recursos que se crearán. Revisa el plan detenidamente antes de aplicar.

Una vez que terraform apply se complete, los siguientes recursos se aprovisionan en su cuenta:

MongoDB Atlas: Acceso a la organización, un nuevo proyecto y un clúster particionado multirregional.
Rol de AWS IAM: un rol que Atlas asume para interactuar con tu cuenta de AWS para el acceso a proveedores de nube.
Puntos finales de AWS VPC: Un punto final de VPC por región, conectado al servicio Atlas PrivateLink para una conectividad privada y segura.
Bucket de AWS S3 : Un bucket para exportaciones de copia de seguridad de Atlas.
VM de validación (opcional, habilitada por defecto): Una instancia EC2 en la subred de la primera región para verificar la conectividad de Atlas a través de PrivateLink.

MongoDB Atlas: Acceso a la organización, un nuevo proyecto y un clúster particionado multirregional.
Principal de servicio de Azure: un principal de servicio de AD de Azure que Atlas utiliza para interactuar con su suscripción de Azure.
Azure nodos privados: Un nodo privado por región, conectado al servicio Atlas PrivateLink para una conectividad privada y segura.
Cuenta de almacenamiento de Azure: una cuenta de almacenamiento y un contenedor Blob para las exportaciones de copias de seguridad de Atlas.
VM de validación (opcional, activada por defecto): Una VM de Linux en la subred de la primera región para verificar la conectividad de Atlas a través de PrivateLink.

MongoDB Atlas: Acceso a la organización, un nuevo proyecto y un clúster particionado multirregional.
Acceso a GCP: Una cuenta de servicio de Atlas autorizada para interactuar con tu proyecto de Google Cloud.
Reglas de reenvío de PSC: Una regla de reenvío de Google Cloud y una dirección de cómputo por región, conectadas al servicio Atlas PrivateLink mediante Private Service Connect (PSC) para una conectividad privada y segura.
GCP Storage Bucket: Un bucket de Google Cloud almacenamiento para exportaciones de copia de seguridad de Atlas.

Validar la implementación

Puedes validar tu implementación con una máquina virtual (VM) que el ejemplo crea para ti, o conectándote directamente con mongosh usando la cadena de conexión PrivateLink.

Conectar y probar con una máquina virtual

Si ha implementado la máquina virtual de validación (activada por defecto), puede utilizarla para verificar la conectividad de Atlas desde su red privada. La máquina virtual tiene mongosh preinstalado y la cadena de conexión preconfigurada.

Toma nota del validation_vm resultado para el ID de instancia y los comandos de acceso:
```
terraform output validation_vm
```
Conectarse a través de AWS Systems Manager (SSM) Session Manager (predeterminado, no se requiere SSH):
```
aws ssm start-session --target <instance-id>
```
Alternativamente, si configura validation_vm_create_ec2_instance_connect_endpoint = true, conéctese a través de EC2 Instance Connect:
```
aws ec2-instance-connect ssh --instance-id <instance-id> --os-user ubuntu
```
Ejecute el script de validación en la máquina virtual para probar la conectividad:
```
./validate-atlas
```
El script confirma que mongosh puede conectarse, y ejecuta operaciones CRUD contra el clúster.

Tome nota de la salida de validation_vm para el nombre de la VM y nombre de usuario:
```
terraform output validation_vm
```
Retrieve the VM password:
```
terraform output -raw validation_vm_password
```
Conéctese a través de la Consola Serial de Azure en el portal de Azure, o a través de Azure Bastion si ha proporcionado una clave SSH con validation_vm_ssh_key.
Ejecute el script de validación en la máquina virtual para probar la conectividad:
```
./validate-atlas
```
El script confirma que mongosh puede conectarse, y ejecuta operaciones CRUD contra el clúster.

El ejemplo de Google Cloud actualmente no incluye una máquina virtual de validación. Utiliza el método de conexión mongosh que aparece a continuación para verificar tu implementación. Se debe ejecutar mongosh desde una de las subredes de Google Cloud para que este método sea exitoso.

Conéctese y realice pruebas con mongosh

También puede probar la conectividad desde cualquier host que pueda acceder a su red privada.

Recupera la cadena de conexión.
Una vez que la implementación se haya completado, recuperar la cadena de conexión de PrivateLink de los Terraform outputs:
```
terraform output connection_string
```
La cadena de conexión utiliza el formato SRV del endpoint privado y enruta el tráfico a través de su conexión PrivateLink.
Ejecuta el siguiente comando, sustituyendo <connection-string> con el valor del comando terraform output connection_string:
```
mongosh "<connection-string>"
```
Después de conectar, ejecuta los siguientes comandos para guardar y recuperar un documento de prueba:
```
db.test.insertOne({ msg: "Hello Atlas" })
db.test.findOne()
```

Una respuesta exitosa confirma que tu clúster es accesible y acepta operaciones de lectura y guardado.

(opcional) Limpiar recursos

Para desinstalar todos los recursos aprovisionados por esta implementación y evitar cargos no deseados, ejecuta:

terraform destroy -var-file terraform.tfvars

Advertencia

terraform destroy elimina permanentemente todos los recursos gestionados por esta configuración, incluido el clúster de Atlas y sus datos. Haz una copia de seguridad de todos los datos que quieras conservar antes de ejecutar este comando.

Recursos adicionales

Repositorio de ejemplos de Atlas: Ejemplos completos y ejecutables de Terraform para AWS, Azure y Google Cloud.
Módulos de Terraform-MongoDB Atlas: El namespace oficial del registro de módulos de Terraform con todos los módulos disponibles.
Atlas Terraform Provider: Documentación técnica completa del proveedor.
Comenzar con Terraform: Una guía de inicio rápido para aprovisionar un clúster básico de Atlas con Terraform.
Orientación para organizaciones, proyectos y clústeres de Atlas: Orientación de Atlas Architecture Center para diseñar su infraestructura Atlas.

Volver

Comience con Terraform

APIs de GraphQL en AWS