🌐 Como o Terraform funciona?

O Terraform cria e gerencia recursos em plataformas de nuvem e outros serviços por meio de suas APIs. Os providers são plugins que permitem ao Terraform trabalhar com praticamente qualquer plataforma ou serviço que possua uma API acessível.

🧭 Por que Infraestrutura como Código?

Escrever infraestrutura como código significa descrever o estado final desejado em arquivos declarativos, em vez de executar passos manuais em consoles web. O código pode ser versionado em Git, revisado em pull requests e reutilizado entre ambientes.

🧱 Blocos e Labels

Um bloco é um contêiner de conteúdo com um tipo e zero ou mais labels. O bloco resource exige dois labels: o tipo do recurso (definido pelo provider) e um nome local arbitrário que você escolhe.

resource "aws_instance" "web" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  network_interface {
    # ...
  }
}

O corpo do bloco é delimitado por { e }, e pode aninhar outros blocos e argumentos. A maioria dos recursos do Terraform (resources, data sources, variables, outputs etc.) é implementada como blocos de nível superior.

🟰 Argumentos e Expressões

Um argumento atribui um valor a um nome. O contexto define os tipos válidos, e a maioria dos argumentos aceita expressões — valores literais, referências a outros recursos, chamadas de função e operações.

image_id = "abc123"
subnet_id = aws_subnet.main.id
name     = "${var.environment}-web-server"
enabled  = length(var.subnet_ids) > 0

Identificadores aceitam letras, dígitos, _ e -, mas nunca começam com dígito.

📜 Declarando providers exigidos

Declare o provider no bloco required_providers, dentro do bloco terraform: a chave é o nome local, e o valor traz o source (endereço global) e a restrição de version.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

O endereço de origem segue o formato [<HOSTNAME>/]<NAMESPACE>/<TYPE>; sem hostname, assume-se registry.terraform.io. Rode terraform init para instalar o provider.

🔢 Restrições de versão

Cada provider evolui independentemente; por isso a documentação recomenda fortemente declarar uma restrição de versão para cada um deles.

O operador ~> permite incrementar apenas o componente mais à direita da versão. O módulo raiz deve limitar a versão máxima para evitar upgrades acidentais.

🏗️ Sintaxe do bloco resource

resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  tags = {
    Name = "web-server"
  }
}

O endereço deste recurso na configuração é aws_instance.web. Os argumentos específicos (como ami) são definidos pelo schema do provider; os meta-arguments (count, for_each, depends_on, lifecycle, provider) são definidos pelo próprio Terraform.

♻️ O ciclo de vida no apply

Ao aplicar uma configuração, o Terraform executa estas operações:

🏪 Backends: onde o state mora

Backends determinam onde o state é armazenado e oferecem uma API para state locking. O backend padrão é o local, que grava um arquivo JSON no disco; backends remotos como s3 e remote (HCP Terraform) guardam o state fora da máquina.

terraform {
  backend "s3" {
    bucket = "meu-state-bucket"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

Com backend não-local, o Terraform não persiste o state em disco — grande benefício quando há valores sensíveis no state. Todos os comandos (terraform state, console, taint…) continuam funcionando como se o state fosse local.

🔒 Locking e dados sensíveis

Se o backend suportar, o Terraform trava o state automaticamente em todas as operações que podem escrevê-lo, impedindo que duas pessoas escrevam ao mesmo tempo e corrompam o arquivo. Se o desbloqueio automático falhar, existe o comando terraform force-unlock <LOCK_ID> — use com muito cuidado e apenas para o seu próprio lock.

🌳 Raiz e filhos

Todo workspace tem um módulo raiz (os arquivos do diretório de trabalho). Os módulos chamados via blocos module são os módulos filhos — e um filho pode chamar seus próprios módulos aninhados.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"

  name = "minha-vpc"
  cidr = "10.0.0.0/16"
}

O terraform init baixa o código do módulo para o disco local (diretório .terraform) durante a etapa de instalação.

📍 Fontes de módulos (source)

🔢 count

Aceita um número inteiro e cria aquela quantidade de instâncias. Cada instância é identificada por count.index, que começa em 0. O valor precisa ser conhecido antes de qualquer operação remota.

resource "aws_instance" "server" {
  count = 4 # cria quatro instâncias EC2 semelhantes

  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  tags = {
    Name = "Server ${count.index}"
  }
}

As instâncias são referenciadas como aws_instance.server[0], [1]… Dica: count = var.habilitar ? 1 : 0 é o padrão clássico de recurso condicional.

🗂️ for_each

Aceita um map ou um set de strings e cria uma instância por elemento, identificada por each.key e each.value. Listas precisam ser convertidas com toset().

resource "azurerm_resource_group" "rg" {
  for_each = tomap({
    a_group       = "eastus"
    another_group = "westus2"
  })
  name     = each.key
  location = each.value
}

🔗 depends_on

Serve para dependências ocultas: quando um recurso depende do comportamento de outro, mas não usa nenhum dado dele em seus argumentos (ex.: uma instância que precisa de uma policy de IAM aplicada antes do boot).

resource "aws_instance" "example" {
  iam_instance_profile = aws_iam_instance_profile.example

  # Dependência que o Terraform não consegue inferir:
  depends_on = [
    aws_iam_role_policy.example
  ]
}

Use como último recurso: ele torna os planos mais conservadores (mais valores "known after apply"). Prefira referências em expressões, que criam dependências implícitas mais precisas.

🧬 lifecycle

🧭 Como funcionam

Todo diretório inicializado começa com um workspace chamado default. Apenas um workspace está selecionado por vez, e a maioria dos comandos interage somente com ele. Com state local, os states ficam no diretório terraform.tfstate.d.

$ terraform workspace list
$ terraform workspace new staging
$ terraform workspace select staging
$ terraform workspace show
$ terraform workspace delete staging

🎯 Quando usar (e quando não usar)

🗂️ Estrutura de arquivos recomendada

backend.tf    # configuração do backend
main.tf       # blocos resource e data
outputs.tf    # outputs em ordem alfabética
providers.tf  # blocos provider
terraform.tf  # required_version e required_providers
variables.tf  # variables em ordem alfabética
locals.tf     # valores locais

Rode terraform fmt e terraform validate sempre (idealmente no CI) para manter estilo e consistência.

🙈 O que NÃO commitar (.gitignore)