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:

Ejecute este generador@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project

yarn

$ yarn nx g @aws/nx-plugin:terraform#project

npm

$ npx nx g @aws/nx-plugin:terraform#project

bun

$ bunx nx g @aws/nx-plugin:terraform#project

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
6. Haga clic en Generate

Construya su comando5

nameRequerido

type

applicationlibrary

directory

subDirectory

preferInstallDependencies

true

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

Opciones

Opciones del generador5 opciones

nameRequeridostring

El nombre del proyecto.

typeenumPredeterminado: application

Si esto es una lib de terraform (módulos reutilizables) o app (desplegable).

applicationlibrary

directorystringPredeterminado: packages

El directorio del nuevo proyecto.

subDirectorystring

El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.

preferInstallDependenciesbooleanPredeterminado: 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, bootstrap-destroy 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
  • bootstrap-destroy.ts Empties the state bucket and runs terraform destroy
  • init.ts Runs terraform init with the S3 backend config
  • env.ts Points terraform init at the shared provider cache
• checkov.yml Checkov configuration, including the checks to skip
• 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
• checkov.yml Checkov configuration, including the checks to skip
• 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"
}

Ten en cuenta que el bucket S3 anterior fallaría el escaneo de seguridad de Checkov, que verifica que el bucket tenga habilitadas las configuraciones de seguridad apropiadas.

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"
aws_region  = "us-west-2"

Nombres de variables

Cada nombre que establezcas aquí debe estar declarado en src/variables.tf — el generador declara aws_region y environment.

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/prod.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

Linting

Los proyectos Terraform usan terraform fmt para verificar el formato.

Ejecutar el Linter

Para invocar el linter y verificar tu proyecto, puedes ejecutar el target lint.

pnpm

pnpm nx lint tf-infra

yarn

yarn nx lint tf-infra

npm

npx nx lint tf-infra

bun

bunx nx lint tf-infra

Corregir Problemas de Lint

La mayoría de los problemas de linting o formato se pueden corregir automáticamente ejecutando con el argumento --configuration=fix.

pnpm

pnpm nx lint tf-infra --configuration=fix

yarn

yarn nx lint tf-infra --configuration=fix

npm

npx nx lint tf-infra --configuration=fix

bun

bunx nx lint tf-infra --configuration=fix

De manera similar, si deseas corregir todos los problemas de lint en todos los paquetes de tu workspace, puedes ejecutar:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix

Comando Abreviado

Esto tiene un comando abreviado desde la raíz de tu workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Omitir Problemas de Lint

Para evitar que los problemas de linting te ralenticen durante el desarrollo (particularmente si tienes problemas no auto-corregibles en tu proyecto), puedes ejecutar una compilación con la configuración skip-lint:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Esto omite la verificación de formato por completo durante la compilación.

Comando Abreviado

Esto tiene un comando abreviado desde la raíz de tu workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint

Pruebas de Seguridad

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

pnpm

pnpm nx checkov tf-infra

yarn

yarn nx checkov tf-infra

npm

npx nx checkov tf-infra

bun

bunx nx checkov tf-infra

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

Checkov se ejecuta como parte de build.

Las verificaciones se configuran en el checkov.yml del proyecto. Agrega un id de verificación a skip-check para suprimirlo en todo el proyecto:

checkov.yml

skip-check:
  - CKV_AWS_115 # Concurrent execution limit
  - CKV_AWS_116 # Dead Letter Queue

Para suprimir una verificación para un solo recurso, agrega un comentario #checkov:skip=<id>:<reason> dentro del bloque del recurso:

resource "aws_s3_bucket" "example" {
  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
  bucket = "example"
}

Ejecutar Pruebas de Terraform

El target test ejecuta el framework de pruebas nativo de Terraform sobre cualquier archivo .tftest.hcl en tu proyecto:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

Un proyecto sin archivos de prueba es un éxito sin operación, por lo que puedes agregar pruebas cuando las necesites. build ejecuta este target, por lo que tus pruebas se ejecutan como parte de una compilación normal.

Cada bloque run evalúa tu configuración. Usa command = plan para verificar qué haría Terraform (esto expande todo el grafo de módulos, por lo que captura errores en tiempo de planificación que validate no puede), o command = apply para crear recursos reales y hacer aserciones sobre sus salidas. Declarar mock_provider significa que no se realizan llamadas a la API y no se necesitan credenciales de AWS, lo que mantiene las pruebas plan rápidas y seguras para ejecutar en CI:

src/main.tftest.hcl

mock_provider "aws" {
  mock_data "aws_caller_identity" {
    defaults = { account_id = "123456789012" }
  }
  mock_data "aws_region" {
    defaults = { region = "us-east-1" }
  }
}

variables {
  aws_region  = "us-east-1"
  environment = "dev"
}

run "plan_is_valid" {
  command = plan

  assert {
    condition     = data.aws_caller_identity.current.account_id == "123456789012"
    error_message = "Unexpected account id"
  }
}

Establece cada variable que tu configuración requiere en el bloque variables, de lo contrario la ejecución falla con “has a required variable … with no set value”.

Cada target que ejecuta terraform init reutiliza un caché de proveedores bajo .terraform/plugin-cache en la raíz de tu workspace, por lo que los proveedores se descargan una vez en lugar de en cada ejecución. Cada proyecto obtiene su propio directorio allí: dos ejecuciones de terraform init llenando un caché al mismo tiempo pueden calcular cada una un hash diferente para el mismo proveedor, que terraform luego rechaza contra tu .terraform.lock.hcl. Consulta la documentación de Terraform para más información.

Establece TF_PLUGIN_CACHE_DIR en tu entorno para apuntar el script init proporcionado a un caché que administres tú mismo — un volumen compartido entre workspaces, por ejemplo. Ten en cuenta que el target test lee su ruta desde project.json, así que cámbialo allí también.

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.

plan depende de assemble, por lo que produce los artefactos que tus módulos referencian, como los bundles de Lambda y los metadatos de operaciones generados, sin ejecutar las compuertas de lint, test y type-check.

Usa build en tu pipeline

assemble se usa para una iteración más rápida durante el desarrollo. Ejecuta build en tu pipeline de CI para asegurar que tu proyecto pase las compuertas de calidad antes de un despliegue a producción.

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

Esto vacía el bucket de estado antes de destruirlo, y resuelve la región desde la cadena de credenciales del AWS SDK, por lo que se ejecuta sin supervisión en CI.

Destruye tu infraestructura primero

El bucket de estado contiene el estado de cada entorno, así que ejecuta destroy para cada entorno antes de esto. Una vez que el bucket desaparece, Terraform ya no sabe sobre los recursos que creó.

Más Información

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