Infraestrutura Terraform

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

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

Uso

Gerar um Projeto Terraform

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

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

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	The name of the project.
type	string	application	Whether this is a terraform lib (re-usable modules) or app (deployable).
directory	string	packages	The directory of the new project.

Saída do Gerador

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

Tipo Aplicação

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

• Directorysrc

  • main.tf Arquivo principal de configuração Terraform
  • providers.tf Configuração de provedores com backend S3
  • variables.tf Definições de variáveis de entrada
  • outputs.tf Definições de valores de saída
  • Directoryenv Arquivos de variáveis específicas do ambiente

    • dev.tfvars Variáveis do ambiente de desenvolvimento
• Directorybootstrap Configuração de bootstrap para estado remoto

  • main.tf Bucket S3 e políticas para armazenamento de estado
  • providers.tf Configuração do provedor AWS
  • variables.tf Definições de variáveis do bootstrap
• project.json Configuração do projeto e targets de build

Nota

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

Tipo Biblioteca

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

• Directorysrc

  • main.tf Arquivo principal do módulo Terraform
• project.json Configuração do projeto e targets de build

Dica

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 sua infraestrutura aqui
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 (biblioteca), pode fazê-lo da seguinte forma:

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

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

Configuração de Ambiente

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

Para adicionar novos ambientes, crie um novo arquivo src/env/<ambiente>.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

# Variáveis de ambiente de produção
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": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=my-scope-my-project/dev/terraform.tfstate\""
                },
                "prod": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=my-scope-my-project/prod/terraform.tfstate\""
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            }
        },
        "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"]
        }
    }
}

Dica

Por padrão, todos os targets assumem o ambiente dev, porém você pode especificar um ambiente como segue:

• pnpm
• yarn
• npm
• bun

pnpm nx run tf-infra:apply --configuration=prod

yarn nx run tf-infra:apply --configuration=prod

npx nx run tf-infra:apply --configuration=prod

bunx nx run tf-infra:apply --configuration=prod

Você também pode alternar entre ambientes a qualquer momento pois o estado segmenta automaticamente o tfstate entre ambientes.

Bootstrap de Estado Remoto (Apenas Projetos de Aplicação)

Para projetos de aplicação, antes de implantar sua infraestrutura, você precisará executar o bootstrap do backend de estado remoto. Isso cria um bucket S3 para armazenar seus arquivos de estado Terraform:

pnpm

pnpm nx run tf-infra:bootstrap

yarn

yarn nx run tf-infra:bootstrap

npm

npx nx run tf-infra:bootstrap

bun

bunx nx run tf-infra:bootstrap

Nota

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

O target bootstrap está disponível apenas para projetos do tipo aplicação. 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 de seu projeto:

Targets Comuns (Aplicação e Biblioteca)

Validando sua Infraestrutura

Valide sua configuração Terraform usando o target validate:

pnpm

pnpm nx run tf-infra:validate

yarn

yarn nx run tf-infra:validate

npm

npx nx run tf-infra:validate

bun

bunx nx run tf-infra:validate

Formatando seu Código

Formate seu código Terraform usando o target fmt:

pnpm

pnpm nx run tf-infra:fmt

yarn

yarn nx run tf-infra:fmt

npm

npx nx run tf-infra:fmt

bun

bunx nx run tf-infra:fmt

Testes de Segurança

Execute verificações de segurança em sua infraestrutura usando Checkov com o target test:

pnpm

pnpm nx run tf-infra:test

yarn

yarn nx run tf-infra:test

npm

npx nx run tf-infra:test

bun

bunx nx run tf-infra:test

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

Targets Exclusivos de Aplicação

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

Planejando sua Infraestrutura

Antes de aplicar mudanças, você pode ver o que o Terraform fará executando o target plan:

pnpm

pnpm nx run tf-infra:plan

yarn

yarn nx run tf-infra:plan

npm

npx nx run tf-infra:plan

bun

bunx nx run tf-infra:plan

Isso criará um arquivo de plano em dist/packages/<meu-projeto-terraform>/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 o planejamento, você pode implantar sua infraestrutura na AWS usando o target apply:

pnpm

pnpm nx run tf-infra:apply

yarn

yarn nx run tf-infra:apply

npm

npx nx run tf-infra:apply

bun

bunx nx run tf-infra:apply

Dica

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

Obtendo Outputs

Recupere valores de saída de sua configuração Terraform:

pnpm

pnpm nx run tf-infra:output

yarn

yarn nx run tf-infra:output

npm

npx nx run tf-infra:output

bun

bunx nx run tf-infra:output

Destruindo Infraestrutura

Quando precisar remover sua infraestrutura, use o target destroy:

pnpm

pnpm nx run tf-infra:destroy

yarn

yarn nx run tf-infra:destroy

npm

npx nx run tf-infra:destroy

bun

bunx nx run tf-infra:destroy

Cuidado

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 run tf-infra:bootstrap-destroy

yarn

yarn nx run tf-infra:bootstrap-destroy

npm

npx nx run tf-infra:bootstrap-destroy

bun

bunx nx run tf-infra:bootstrap-destroy

Mais Informações

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