[PT-BR] Guia de Módulo OpenTofu AWS EC2: Requisitos, Test...

Introdução

A criação de módulos reutilizáveis para provisionamento de instâncias EC2 na AWS é uma prática essencial para equipes que buscam infraestrutura como código (IaC) consistente, segura e escalável. Um módulo bem‑escrito vai além da definição de recursos, exige planejamento de requisitos, suíte de testes automatizados e abordagem orientada ao comportamento (BDD) para garantir que atenda às necessidades de negócio e operacionais. Este guia substitui o uso do Terraform pelo OpenTofu, uma ferramenta que surgiu como um fork da última versão de código aberto do Terraform (1.5.7) e é mantida sob governança neutra da Linux Foundation, oferecendo alternativa totalmente open‑source sob a licença MPL.

Todo o conteúdo apresentado a seguir é totalmente compatível com o OpenTofu: o provedor AWS utilizado é exatamente o mesmo, a sintaxe HCL é idêntica, e o fluxo de trabalho permanece praticamente inalterado. Portanto, você pode aplicar este guia diretamente em seus projetos com OpenTofu sem qualquer modificação adicional.

1. Requisitos para Gerar um Módulo OpenTofu de EC2

1.1 Pré‑requisitos de Infraestrutura e CLI

· OpenTofu CLI instalado (versão 1.6.0 ou superior).
· AWS CLI configurada com credenciais que tenham permissões para criar EC2, VPC, sub‑redes e grupos de segurança.
· Um par de chaves SSH (key pair) existente na AWS, utilizado para acesso à instância.
· Uma VPC e pelo menos uma sub‑rede (subnet) onde a instância será lançada. O ID da sub‑rede é um parâmetro obrigatório para o módulo.

1.2 Estrutura Essencial do Módulo

Um módulo deve seguir uma estrutura padrão, composta por três arquivos principais dentro de um diretório (ex.: modules/ec2/):

· main.tofu: contém o recurso aws_instance e demais recursos associados.
· variables.tofu: declara todas as variáveis de entrada.
· outputs.tofu: expõe informações úteis como ID da instância e IP público.

Alternativamente, você pode manter a extensão .tf – o OpenTofu lê ambos os formatos perfeitamente.

1.3 Componentes Obrigatórios no main.tofu

resource "aws_instance" "this" {
  ami                    = var.ami_id
  instance_type          = var.instance_type
  subnet_id              = var.subnet_id
  vpc_security_group_ids = var.security_group_ids
  key_name               = var.key_name
  tags                   = var.tags
}

Argumentos adicionais, como user_data, root_block_device e ebs_block_device, podem ser incluídos conforme a necessidade.

1.4 Boas Práticas de Segurança e Organização

· Não inserir credenciais diretamente no módulo; utilizar variáveis de ambiente ou backend remoto.
· Validar variáveis com blocos validation (ex.: restringir instance_type a uma lista permitida).
· Documentar todas as variáveis e outputs no arquivo README.md.
· Utilizar namespaces consistentes nas tags (ex.: Environment, Application).

2. Plano de Testes para o Módulo EC2

Um módulo só é confiável se for testado adequadamente. O plano a seguir cobre desde verificações estáticas até testes de integração e testes nativos do OpenTofu.

2.1 Tipos de Teste e Ferramentas

Tipo de Teste | Objetivo | Ferramentas
Análise estática | Validar sintaxe, formatação e boas práticas | tofu fmt, tofu validate, tflint (com wrapper)

Análise de segurança | Identificar configurações inseguras (portas abertas, falta de criptografia) | checkov, tfsec, tofu_checkov

Teste de unidade (mock) | Executar o módulo em ambiente simulado | tofu test com simulação de provedores

Teste de integração nativo | Provisionar recursos reais e realizar asserções diretamente em HCL | tofu test (comandos nativos)

Teste de integração avançado | Testes mais complexos com orquestração em Go | Terratest (compatível com OpenTofu)

Teste de regressão | Verificar se mudanças não quebram versões anteriores | tofu test + versionamento do módulo

2.2 Fase 1: Testes Estáticos

Execute os comandos na raiz do módulo:

tofu fmt -recursive -check
tofu init -backend=false
tofu validate
tflint --init && tflint
checkov -d .

Critério de sucesso: nenhum erro ou warning crítico. O tflint pode ser utilizado com o wrapper para OpenTofu, e ferramentas como tofu_checkov estão disponíveis para substituir o checkov legado.

2.3 Fase 2: Testes de Segurança (checkov/tfsec)

Verificações obrigatórias:

· A instância não deve estar em sub‑rede pública sem restrições.
· O grupo de segurança não deve permitir 0.0.0.0/0 para SSH (porta 22) em produção.
· Volumes EBS devem ter encrypted = true.
· O módulo não deve expor variáveis sensíveis nos outputs.

O OpenTofu é suportado nativamente por essas ferramentas de análise estática.

2.4 Fase 3: Testes Nativos com tofu test

A partir da versão 1.6, o OpenTofu inclui o comando tofu test, que permite escrever testes de integração diretamente em HCL. O comando cria infraestrutura real (em uma conta AWS de teste), executa asserções e, ao final, destrói os recursos criados automaticamente.

Exemplo de arquivo de teste (tests/ec2.tofutest.hcl)

# tests/ec2.tofutest.hcl
run "basic_ec2_creation" {
  command = plan

  variables {
    instance_name = "test-instance"
    ami_id        = "ami-0c02fb55956c7d316"
    instance_type = "t3.micro"
    subnet_id     = "subnet-12345678"
    key_name      = "my-key"
    security_group_ids = ["sg-12345678"]
  }

  assert {
    condition     = aws_instance.this.instance_type == "t3.micro"
    error_message = "Instance type não corresponde ao esperado"
  }

  assert {
    condition     = aws_instance.this.tags["Name"] == "test-instance"
    error_message = "Tag Name não foi aplicada corretamente"
  }
}

Para executar:

cd modules/ec2
tofu init
tofu test -test-directory=tests

O OpenTofu executará o teste, criando recursos reais e destruindo‑os ao final. A partir da versão 1.8, o tofu test também suporta a simulação de provedores completos, o que facilita testes de unidade sem depender de recursos externos.

2.5 Fase 4: Testes de Integração Avançados com Terratest

Para cenários que exigem mais controle ou múltiplas etapas, o Terratest (framework em Go) pode ser utilizado. Como o OpenTofu é um substituto direto (“drop‑in replacement”) do Terraform, nenhuma alteração no código dos testes é necessária – basta garantir que o binário tofu esteja disponível no ambiente.

Exemplo simplificado:

package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/gruntwork-io/terratest/modules/aws"
    "github.com/stretchr/testify/assert"
)

func TestEC2Module(t *testing.T) {
    t.Parallel()

    terraformOptions := &terraform.Options{
        TerraformDir: "../fixtures",
        Vars: map[string]interface{}{
            "instance_name": "integration-test",
            "ami_id":        "ami-0c02fb55956c7d316",
            "instance_type": "t3.micro",
            "subnet_id":     "subnet-12345678",
            "key_name":      "my-key",
            "security_group_ids": []string{"sg-12345678"},
        },
    }

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    instanceID := terraform.Output(t, terraformOptions, "instance_id")
    instance := aws.GetEc2InstanceById(t, instanceID, "us-east-1")
    assert.Equal(t, "running", instance.State.Name)
}

Cenários a serem cobertos:

· Criação básica (valores mínimos).
· Com user_data para executar script de bootstrap.
· Com volume EBS adicional.
· Com tipo de instância inválido (deve falhar).
· Destruição limpa (verificar ausência de recursos órfãos).

2.6 Critérios de Aceitação do Plano de Testes

· tofu validate: sem erros.
· tofu fmt: 0 diferenças.
· tflint (com wrapper): sem warnings de nível ERROR.
· checkov/tofu_checkov: todos os checks de severidade HIGH aprovados.
· tofu test: todos os cenários de teste nativos aprovados.
· Teste de criação básica (via Terratest): sucesso.
· Teste de conectividade SSH: sucesso.
· Teste de destruição: nenhum recurso remanescente.

3. Estratégia BDD (Behavior-Driven Development) para o Módulo EC2

O BDD permite descrever o comportamento esperado em linguagem natural, garantindo que o módulo atenda aos requisitos de negócio e operacionais. A ferramenta terraform‑compliance (que é compatível com OpenTofu) permite escrever cenários em Gherkin e validá‑los contra o plano gerado.

3.1 Ferramentas Recomendadas

· terraform-compliance: executa cenários escritos em Gherkin contra o plano do OpenTofu.
· tofu test com blocos run e assert (pode ser usado para validar comportamentos específicos).

3.2 Estrutura de Diretórios para BDD

modules/ec2/tests/bdd/
├── features/
│   ├── creation.feature
│   ├── security.feature
│   ├── connectivity.feature
│   └── destruction.feature
└── steps/
    └── steps.py (opcional, para customizações)

3.3 Exemplos de Cenários Gherkin

Criação básica (creation.feature):

Feature: EC2 Instance Creation

  Scenario: Successfully create an EC2 instance with minimal required parameters
    Given I have a OpenTofu module "ec2" with configuration:
      """
      module "ec2" {
        source      = "../.."
        instance_name = "bdd-test-instance"
        ami_id        = "ami-0c02fb55956c7d316"
        instance_type = "t3.micro"
        subnet_id     = "subnet-12345678"
        key_name      = "my-key"
        security_group_ids = ["sg-12345678"]
      }
      """
    When I apply the OpenTofu configuration
    Then the EC2 instance should exist
    And its state should be "running"
    And it should have tag "Name" with value "bdd-test-instance"

Segurança (security.feature):

Feature: Security Configuration

  Scenario: SSH access should be limited to authorized IPs
    Given I have an EC2 instance created with security group "allow-ssh-from-office"
    When I inspect the security group rules
    Then inbound rule for port 22 should exist
    And the CIDR block should be "203.0.113.0/24"
    And no inbound rule should allow 0.0.0.0/0 for port 22

  Scenario: EBS volumes must be encrypted
    Given I have an EC2 instance with root block device
    Then the "encrypted" attribute of the root volume must be true

Conectividade (connectivity.feature):

Feature: Connectivity and User Data

  Scenario: Instance should be reachable via SSH
    Given I have a running EC2 instance with public IP address
    And I have the private key file "my-key.pem"
    When I try to SSH into the instance as user "ec2-user"
    Then the connection should succeed within 60 seconds

Destruição (destruction.feature):

Feature: Resource Cleanup

  Scenario: All resources are destroyed after deletion
    Given I have applied the EC2 module
    When I run `tofu destroy`
    Then the EC2 instance should no longer exist
    And any associated EBS volumes should be deleted
    And the OpenTofu state should be empty

3.4 Execução com terraform-compliance

Instalação:

pip install terraform-compliance

Execução:

cd modules/ec2/tests/bdd
tofu init
tofu plan -out plan.out
terraform-compliance -f ../features -p plan.out

Integração contínua (GitHub Actions):

- name: Run BDD scenarios
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  run: |
    cd modules/ec2/tests/bdd
    tofu init
    tofu plan -out plan.out
    terraform-compliance -f ../features -p plan.out

3.5 Matriz de Cenários Obrigatórios

Feature | Cenário | Prioridade
Creation | Criar com valores mínimos | Must-have

Security | SSH restrito por IP | Must-have

Security | EBS criptografado | Must-have

Security | Sem portas administrativas para 0.0.0.0/0 | Must-have

Connectivity | SSH reachable | Should-have

Destruction | Destruição remove todos os recursos | Must-have

3.6 Critérios de Aceitação BDD

· 100% dos cenários classificados como “Must‑have” devem ser aprovados.
· Nenhum cenário pode falhar devido a dependências externas (sub‑redes inexistentes, etc.). Utilize variáveis consistentes ou mocks (via tofu test).
· Os arquivos .feature devem ser revisados pelas equipes de operações e segurança.

Conclusão

Desenvolver um módulo OpenTofu para EC2 vai muito além de escrever um recurso aws_instance. É necessário planejar requisitos, estruturar código de forma reutilizável/segura, implementar bateria de testes (estáticos, de segurança, integração nativa com tofu test, e destrutivos) e adotar estratégia BDD para alinhar o comportamento do módulo às expectativas de negócio.

A transição para o OpenTofu não exige mudanças no código que é um substituto direto do Terraform, com a vantagem adicional de ser totalmente open‑source e governado pela comunidade, eliminando questões de licenciamento e garantindo a perenidade do seu investimento em IaC.

Ao seguir este guia, você terá um módulo robusto, testável e production ready, além de facilitar a colaboração entre equipes de desenvolvimento, operações e segurança.

Referências

推荐订阅源