Infraestrutura Terraform

Terraform é uma ferramenta de software de infraestrutura como código de código aberto que permite criar, alterar e melhorar a infraestrutura de forma segura e previsível.

O gerador de infraestrutura Terraform cria um projeto de infraestrutura Terraform. A aplicação gerada inclui práticas recomendadas de segurança através de verificações de segurança do Checkov.

Uso

Gerar um Projeto Terraform

Você pode gerar um novo projeto Terraform de duas maneiras:

Execute este gerador@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 o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - terraform#project
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Monte seu comando5

nameObrigatório

type

applicationlibrary

directory

subDirectory

preferInstallDependencies

true

--dry-runVocê também pode realizar uma execução simulada para ver quais arquivos seriam alterados

Opções

Opções do gerador5 opções

nameObrigatóriostring

O nome do projeto.

typeenumPadrão: application

Se este é uma lib terraform (módulos reutilizáveis) ou app (implantável).

applicationlibrary

directorystringPadrão: packages

O diretório do novo projeto.

subDirectorystring

O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.

preferInstallDependenciesbooleanPadrão: true

Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador cria diferentes estruturas de arquivos dependendo do tipo de projeto:

type = application

Tipo Application

Para projetos de aplicação (--type=application), o gerador cria uma aplicação Terraform completa com gerenciamento de estado remoto:

• Directorysrc

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

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

  • main.tf S3 bucket and policies for state storage
  • providers.tf AWS provider configuration
  • variables.tf Bootstrap variable definitions
• Directoryscripts 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 Compartilhados

O gerador também cria uma biblioteca packages/common/terraform que inicialmente apenas adiciona um módulo de métricas (cria uma pilha Cloudformation vazia com metadados) que é automaticamente instrumentado para que a equipe do nx-plugin-for-aws possa rastrear métricas de uso.

type = library

Tipo Library

Para projetos de biblioteca (--type=library), o gerador cria uma estrutura mais simples para módulos Terraform reutilizáveis:

• Directorysrc

  • 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

Projetos de aplicação incluem capacidades completas de implantação com gerenciamento de estado remoto, enquanto projetos de biblioteca são projetados para criar módulos Terraform reutilizáveis que podem ser consumidos por outros projetos.

Implementando sua Infraestrutura Terraform

Você pode começar a escrever sua infraestrutura Terraform dentro de src/main.tf, por exemplo:

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

Observe que o bucket S3 acima falharia na verificação de segurança do Checkov, que verifica se o bucket tem as configurações de segurança apropriadas habilitadas.

Dependências entre projetos

Se você quiser executar um módulo de um projeto separado (lib), você pode fazer isso da seguinte forma:

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

Isso atualizará automaticamente o grafo Nx para adicionar uma dependência entre sua aplicação consumidora e sua lib.

Configuração de Ambiente

Configure variáveis específicas do ambiente nos arquivos src/env/*.tfvars.

Para adicionar novos ambientes, crie um novo arquivo src/env/<environment>.tfvars com as variáveis específicas do ambiente e adicione novas entradas para apply, destroy, init, plan no project.json para a nova configuração de ambiente. Por exemplo, vamos supor que queremos adicionar um ambiente prod:

src/env/prod.tfvars

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

Nomes de variáveis

Cada nome que você definir aqui deve ser declarado em src/variables.tf — o gerador declara aws_region e 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"]
        }
    }
}

Ambiente Padrão

Por padrão, todos os targets assumem o ambiente dev, no entanto você pode direcionar um ambiente específico da seguinte forma:

• 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

Você também pode trocar de ambiente a qualquer momento, pois o estado segmenta o tfstate automaticamente entre ambientes.

type = application

Bootstrap de Estado Remoto (Somente Projetos Application)

Antes de implantar sua infraestrutura, você precisará fazer o bootstrap do backend de estado remoto. Isso cria um bucket S3 para armazenar seus arquivos de estado 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

Configuração de Perfil AWS

Certifique-se de que seu perfil AWS CLI está configurado para a conta/região na qual você deseja implantar os recursos de bootstrap.

O target bootstrap está disponível apenas para projetos do tipo application. Projetos de biblioteca não requerem gerenciamento de estado remoto, pois são projetados para serem módulos reutilizáveis.

Targets Disponíveis

Os targets disponíveis dependem do tipo do seu projeto:

Targets Comuns (Application e Library)

Validando sua Infraestrutura

Você pode validar sua configuração Terraform usando o 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

Projetos Terraform usam terraform fmt para verificar a formatação.

Executando o Linter

Para invocar o linter para verificar seu projeto, você pode executar o 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

Corrigindo Problemas de Lint

A maioria dos problemas de linting ou formatação pode ser corrigida automaticamente executando com o 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

Da mesma forma, se você quiser corrigir todos os problemas de lint em todos os pacotes no seu workspace, você pode executar:

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

Isso tem um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Pulando Problemas de Lint

Para evitar que problemas de linting te atrasem durante o desenvolvimento (particularmente se você tiver problemas não corrigíveis automaticamente no seu projeto), você pode executar um build com a configuração 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

Isso pula a verificação de formato inteiramente durante o build.

Comando Abreviado

Isso tem um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint

Testes de Segurança

Execute verificações de segurança em sua infraestrutura usando Checkov com o 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

Você encontrará os resultados dos testes de segurança na pasta dist raiz, em dist/packages/<my-terraform-project>/checkov.

Checkov é executado como parte do build.

As verificações são configuradas no checkov.yml do projeto. Adicione um id de verificação ao skip-check para suprimi-lo em todo o projeto:

checkov.yml

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

Para suprimir uma verificação para um único recurso, adicione um comentário #checkov:skip=<id>:<reason> dentro do bloco do recurso:

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

Executando Testes Terraform

O target test executa o framework de testes nativo do Terraform sobre quaisquer arquivos .tftest.hcl no seu projeto:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

Um projeto sem arquivos de teste é um sucesso sem operação, então você pode adicionar testes quando precisar deles. O build executa este target, então seus testes são executados como parte de um build normal.

Cada bloco run avalia sua configuração. Use command = plan para verificar o que o Terraform faria (isso expande todo o grafo de módulos, então captura erros em tempo de planejamento que o validate não consegue), ou command = apply para criar recursos reais e fazer asserções sobre suas saídas. Declarar mock_provider significa que nenhuma chamada de API é feita e nenhuma credencial AWS é necessária, o que mantém os testes plan rápidos e seguros para executar em 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"
  }
}

Defina todas as variáveis que sua configuração requer no bloco variables, caso contrário a execução falhará com “has a required variable … with no set value”.

Cada target que executa terraform init reutiliza um cache de provedores em .terraform/plugin-cache na raiz do seu workspace, então os provedores são baixados uma vez em vez de a cada execução. Cada projeto obtém seu próprio diretório lá: duas execuções de terraform init preenchendo um cache ao mesmo tempo podem cada uma calcular um hash diferente para o mesmo provedor, que o terraform então rejeita contra seu .terraform.lock.hcl. Consulte a documentação do Terraform para mais informações.

Defina TF_PLUGIN_CACHE_DIR no seu ambiente para apontar o script init fornecido para um cache que você gerencia — um volume compartilhado entre workspaces, por exemplo. Observe que o target test lê seu caminho do project.json, então altere-o lá também.

type = application

Targets Exclusivos de Application

Os seguintes targets estão disponíveis apenas para projetos do tipo application:

Planejando sua Infraestrutura

Antes de aplicar mudanças, você pode ver o que o Terraform fará executando o 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

Isso criará um arquivo de plano em dist/packages/<my-terraform-project>/terraform/dev.tfplan.

plan depende de assemble, então ele produz os artefatos que seus módulos referenciam, como os bundles Lambda e metadados de operações gerados, sem executar os gates de lint, test e type-check.

Use build no seu pipeline

assemble é usado para iteração mais rápida durante o desenvolvimento. Execute build no seu pipeline de CI para garantir que seu projeto passe pelos gates de qualidade antes de uma implantação em produção.

Inicializando o Terraform

Inicialize seu diretório de trabalho Terraform com o 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

Implantando na AWS

Após planejar, você pode implantar sua infraestrutura na AWS usando o 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

O comando acima aplica o plano criado pelo target plan. Certifique-se de executar plan primeiro para revisar as mudanças.

Alias Deploy

Um target deploy também está disponível como um alias para apply. Você pode usar tanto

• pnpm
• yarn
• npm
• bun

pnpm nx deploy tf-infra

yarn nx deploy tf-infra

npx nx deploy tf-infra

bunx nx deploy tf-infra

quanto

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

de forma intercambiável.

Obtendo Outputs

Recupere valores de saída da sua configuração 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

Destruindo Infraestrutura

Quando você precisar derrubar sua infraestrutura, use o 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

Operação Destrutiva

Isso excluirá permanentemente todos os recursos gerenciados por esta configuração Terraform. Use com cautela!

Destruindo Recursos de Bootstrap

Para limpar os recursos de bootstrap (bucket S3 para armazenamento 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

Isso esvazia o bucket de estado antes de destruí-lo, e resolve a região da cadeia de credenciais do AWS SDK, então é executado sem supervisão em CI.

Destrua sua infraestrutura primeiro

O bucket de estado mantém o estado para cada ambiente, então execute destroy para cada ambiente antes disso. Uma vez que o bucket seja removido, o Terraform não saberá mais sobre os recursos que criou.

Mais Informações

Para mais informações sobre Terraform, consulte a Documentação do Terraform e a Documentação do AWS Provider.