Infraestructura Terraform

Terraform es una herramienta de software de infraestructura como código de código abierto que te permite crear, cambiar y mejorar infraestructura de manera segura y predecible.

El generador de infraestructura Terraform crea un proyecto de infraestructura Terraform. La aplicación generada incluye mejores prácticas de seguridad a través de verificaciones de seguridad de Checkov.

Uso

Generar un Proyecto Terraform

Puedes generar un nuevo proyecto Terraform de dos maneras:

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - terraform#project
5. Complete los parámetros requeridos
   • name: tf-infra
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	El nombre del proyecto.
type	application | library	application	Si esto es una lib de terraform (módulos reutilizables) o app (desplegable).
directory	string	packages	El directorio del nuevo proyecto.
subDirectory	string	-	El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador crea diferentes estructuras de archivos dependiendo del tipo de proyecto:

type = application

Tipo Application

Para proyectos de aplicación (--type=application), el generador crea una aplicación Terraform completa con gestión de estado remoto:

• Directoriosrc

  • main.tf Main Terraform configuration file
  • providers.tf Provider configuration with S3 backend
  • variables.tf Input variable definitions
  • outputs.tf Output value definitions
  • Directorioenv Environment-specific variable files

    • dev.tfvars Development environment variables
• Directoriobootstrap Bootstrap configuration for remote state

  • main.tf S3 bucket and policies for state storage
  • providers.tf AWS provider configuration
  • variables.tf Bootstrap variable definitions
• Directorioscripts Node helpers run by the nx bootstrap and init targets

  • aws-config.ts Resolves account + region via the AWS SDK credential chain
  • bootstrap.ts Pulls/pushes the bootstrap tfstate and runs terraform apply
  • init.ts Runs terraform init with the S3 backend config
• project.json Project configuration and build targets

Módulos Terraform Compartidos

El generador también crea una biblioteca packages/common/terraform que inicialmente solo agrega un módulo de métricas (crea un stack de Cloudformation vacío con metadatos) que se instrumenta automáticamente para que el equipo de nx-plugin-for-aws pueda rastrear métricas de uso.

type = library

Tipo Library

Para proyectos de biblioteca (--type=library), el generador crea una estructura más simple para módulos Terraform reutilizables:

• Directoriosrc

  • main.tf Main Terraform module file
• project.json Project configuration and build targets

Application vs Library

Los proyectos de aplicación incluyen capacidades de despliegue completas con gestión de estado remoto, mientras que los proyectos de biblioteca están diseñados para crear módulos Terraform reutilizables que pueden ser consumidos por otros proyectos.

Implementar tu Infraestructura Terraform

Puedes comenzar a escribir tu infraestructura Terraform dentro de src/main.tf, por ejemplo:

src/main.tf

locals {
  account_id = data.aws_caller_identity.current.account_id
  aws_region = data.aws_region.current.id
}

resource "null_resource" "print_info" {
  # triggers = {
  #   always_run = timestamp()
  # }

  provisioner "local-exec" {
    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
  }
}

# Declare your infrastructure here
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

Dependencias entre proyectos

Si quisieras ejecutar un módulo desde un proyecto separado (lib), podrías hacerlo de la siguiente manera:

module "lib_module" {
  source = "../../path/to/my-lib/src"
}

Esto actualizará automáticamente el grafo de Nx para agregar una dependencia entre tu aplicación consumidora y tu lib.

Configuración de Entorno

Configura variables específicas del entorno en los archivos src/env/*.tfvars.

Para agregar nuevos entornos, crea un nuevo archivo src/env/<environment>.tfvars con las variables específicas del entorno y agrega nuevas entradas para apply, destroy, init, plan en el project.json para la nueva configuración de entorno. Por ejemplo, supongamos que queremos agregar un entorno prod:

src/env/prod.tfvars

# Production environment variables
environment = "prod"
region      = "us-west-2"

project.json

{
  "targets": {
        "apply": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["plan"]
        },
        "destroy": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform destroy -var-file=env/dev.tfvars"
                },
                "prod": {
                    "command": "terraform destroy -var-file=env/prod.tfvars"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd":"{projectRoot}/src"
            },
            "dependsOn": ["init"]
        },
        "init": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "env": { "TF_ENV": "dev" }
                },
                "prod": {
                    "env": { "TF_ENV": "prod" }
                }
            },
            "options": {
                "forwardAllArgs": true,
                "commands": ["tsx {projectRoot}/scripts/init.ts {projectRoot}"],
                "cwd": "{workspaceRoot}"
            }
        },
        "plan": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Entorno Predeterminado

Por defecto, todos los targets asumen el entorno dev, sin embargo puedes apuntar a un entorno específico de la siguiente manera:

• pnpm
• yarn
• npm
• bun

pnpm nx apply tf-infra --configuration=prod

yarn nx apply tf-infra --configuration=prod

npx nx apply tf-infra --configuration=prod

bunx nx apply tf-infra --configuration=prod

También puedes cambiar de entorno en cualquier momento ya que el estado segmenta el tfstate automáticamente entre entornos.

type = application

Bootstrap de Estado Remoto (Solo Proyectos Application)

Antes de desplegar tu infraestructura, necesitarás hacer el bootstrap del backend de estado remoto. Esto crea un bucket S3 para almacenar tus archivos de estado de Terraform:

pnpm

pnpm nx bootstrap tf-infra

yarn

yarn nx bootstrap tf-infra

npm

npx nx bootstrap tf-infra

bun

bunx nx bootstrap tf-infra

Configuración de Perfil AWS

Asegúrate de que tu perfil de AWS CLI esté configurado para la cuenta/región en la que deseas desplegar los recursos de bootstrap.

El target bootstrap solo está disponible para proyectos de tipo application. Los proyectos de biblioteca no requieren gestión de estado remoto ya que están diseñados para ser módulos reutilizables.

Targets Disponibles

Los targets disponibles dependen del tipo de tu proyecto:

Targets Comunes (Tanto Application como Library)

Validar tu Infraestructura

Puedes validar tu configuración de Terraform usando el target validate:

pnpm

pnpm nx validate tf-infra

yarn

yarn nx validate tf-infra

npm

npx nx validate tf-infra

bun

bunx nx validate tf-infra

Formatear tu Código

Formatea tu código Terraform usando el target fmt:

pnpm

pnpm nx fmt tf-infra

yarn

yarn nx fmt tf-infra

npm

npx nx fmt tf-infra

bun

bunx nx fmt tf-infra

Pruebas de Seguridad

Ejecuta verificaciones de seguridad en tu infraestructura usando Checkov con el target test:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

Encontrarás los resultados de tus pruebas de seguridad en la carpeta raíz dist, bajo dist/packages/<my-terraform-project>/checkov.

type = application

Targets Solo para Application

Los siguientes targets solo están disponibles para proyectos de tipo application:

Planificar tu Infraestructura

Antes de aplicar cambios, puedes ver qué hará Terraform ejecutando el target plan:

pnpm

pnpm nx plan tf-infra

yarn

yarn nx plan tf-infra

npm

npx nx plan tf-infra

bun

bunx nx plan tf-infra

Esto creará un archivo de plan en dist/packages/<my-terraform-project>/terraform/dev.tfplan.

Inicializar Terraform

Inicializa tu directorio de trabajo de Terraform con el target init:

pnpm

pnpm nx run tf-infra:init

yarn

yarn nx run tf-infra:init

npm

npx nx run tf-infra:init

bun

bunx nx run tf-infra:init

Desplegar a AWS

Después de planificar, puedes desplegar tu infraestructura a AWS usando el target apply:

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

Auto-Approve

El comando anterior aplica el plan creado por el target plan. Asegúrate de ejecutar plan primero para revisar los cambios.

Alias Deploy

Un target deploy también está disponible como alias para apply. Puedes usar

• pnpm
• yarn
• npm
• bun

pnpm nx deploy tf-infra

yarn nx deploy tf-infra

npx nx deploy tf-infra

bunx nx deploy tf-infra

o

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

indistintamente.

Obtener Outputs

Recupera valores de salida de tu configuración de Terraform:

pnpm

pnpm nx output tf-infra

yarn

yarn nx output tf-infra

npm

npx nx output tf-infra

bun

bunx nx output tf-infra

Destruir Infraestructura

Cuando necesites desmantelar tu infraestructura, usa el target destroy:

pnpm

pnpm nx destroy tf-infra

yarn

yarn nx destroy tf-infra

npm

npx nx destroy tf-infra

bun

bunx nx destroy tf-infra

Operación Destructiva

Esto eliminará permanentemente todos los recursos gestionados por esta configuración de Terraform. ¡Úsalo con precaución!

Destruir Recursos de Bootstrap

Para limpiar los recursos de bootstrap (bucket S3 para almacenamiento de estado):

pnpm

pnpm nx bootstrap-destroy tf-infra

yarn

yarn nx bootstrap-destroy tf-infra

npm

npx nx bootstrap-destroy tf-infra

bun

bunx nx bootstrap-destroy tf-infra

Más Información

Para más información sobre Terraform, consulta la Documentación de Terraform y la Documentación del Proveedor AWS.