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

• https://opentofu.org/blog/opentofu-1-11-0/
• https://docs.opentofu.org
• https://developer.hashicorp.com/terraform/cli/commands/test
• https://terraform-compliance.com
• https://www.checkov.io
• https://github.com/terraform-linters/tflint
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance