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	-	O nome do projeto.
type	string	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.

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

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

Aplicação vs biblioteca

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

Ambiente padrão

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 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 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 bootstrap tf-infra

yarn

yarn nx bootstrap tf-infra

npm

npx nx bootstrap tf-infra

bun

bunx nx bootstrap tf-infra

Configuração do perfil AWS

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 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 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 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/<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 apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

Aprovação automática

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 output tf-infra

yarn

yarn nx output tf-infra

npm

npx nx output tf-infra

bun

bunx nx output tf-infra

Destruindo Infraestrutura

Quando precisar remover 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 o Terraform, consulte a Documentação do Terraform e a Documentação do Provedor AWS.