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:

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

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

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 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
   • name: tf-infra
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	O nome do projeto.
type	application | library	application	Se este é uma lib terraform (módulos reutilizáveis) ou app (implantável).
directory	string	packages	O diretório do novo projeto.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
preferInstallDependencies	boolean	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 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 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
• 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"
}

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

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

Formatando seu Código

Formate seu código Terraform usando o 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

Testes de Segurança

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

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

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.

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

Mais Informações

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