Terraform e estado

Infraestrutura como código na prática: ler HCL, planejar, aplicar e destruir recursos, e cuidar do arquivo de estado.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Explicar o que é infraestrutura como código e o estilo declarativo
  • Identificar provider, resource, variable e output num arquivo HCL
  • Rodar init, plan, apply e destroy e interpretar os símbolos do plano
  • Explicar o que o estado guarda, por que fica fora do Git e para que servem estado remoto e trava
  • Reconhecer drift e saber quando usar um módulo

Pergunte a alguém como foi criado o servidor da empresa e muitas vezes a resposta é “o Carlos clicou no console, mas ele saiu faz um ano”. Ninguém sabe recriar, ninguém sabe o que muda se mexer. Infraestrutura como código resolve isso: o ambiente vira um arquivo que se lê, se revisa num pull request e se recria com um comando. Terraform é a ferramenta mais pedida para isso em vagas de DevOps.

A receita no lugar da memória

Terraform é uma ferramenta de IaC. Você escreve arquivos .tf descrevendo o que deve existir, e ele cria, altera ou apaga recursos para que a realidade fique igual ao arquivo. Funciona com nuvens (AWS, Google, Azure) e também com coisas locais, como containers Docker.

O estilo é declarativo: você diz o resultado (“quero um container site-lab na porta 8080”), não os passos. Se o container já existe igual, o Terraform não faz nada. Rodar duas vezes dá o mesmo resultado, uma propriedade chamada idempotência.

Qual é a maior vantagem de criar um servidor com Terraform em vez de clicar no console do provedor?

  • A configuração fica versionada no Git, pode ser revisada e recriada igual
  • O servidor criado pelo Terraform é mais rápido
  • O Terraform não precisa de permissões na nuvem

Lendo um arquivo Terraform

Os arquivos usam a linguagem HCL. Ela é feita de blocos: uma palavra que diz o tipo, alguns nomes entre aspas e um conteúdo entre chaves. Este exemplo sobe um site Nginx num container Docker no seu próprio computador, sem custo de nuvem.

O arquivo main.tf do laboratório local.

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {}

variable "porta" {
  type    = number
  default = 8080
}

resource "docker_image" "nginx" {
  name = "nginx:1.27"
}

resource "docker_container" "site" {
  name  = "site-lab"
  image = docker_image.nginx.image_id
  ports {
    internal = 80
    external = var.porta
  }
}

output "endereco" {
  value = "http://localhost:${var.porta}"
}
  • Bloco terraform: Diz quais providers o projeto usa e em que versão. Um provider é o “tradutor” entre o Terraform e um sistema: AWS, Docker, GitHub. ~> 3.0 aceita 3.x, mas não 4.0.
  • provider: Configura o provider. Para a AWS, aqui iria a região. Para o Docker local, o padrão já basta.
  • variable: Uma entrada que pode mudar sem editar o resto: como o parâmetro de uma função. Lida em outros lugares como var.porta.
  • resource: Um recurso que deve existir. O primeiro nome é o tipo (docker_image), o segundo é o apelido dentro do projeto (nginx). Juntos, formam o endereço docker_image.nginx.
  • Referência: Um recurso usando outro. Por causa dessa referência, o Terraform sabe que precisa baixar a imagem antes de criar o container.
  • output: Um valor mostrado no fim do apply, como o endereço do site ou o IP de um servidor. Também pode ser lido por outros projetos.

Complete o arquivo: declare a variável, o recurso do container usando a variável e a saída com o endereço.

____ "porta" {
  type    = number
  default = 8080
}

____ "docker_container" "site" {
  name  = "site-lab"
  image = docker_image.nginx.image_id
  ports {
    internal = 80
    external = ____
  }
}

____ "endereco" {
  value = "http://localhost:${var.porta}"
}

Planejar, aplicar, destruir

O ciclo tem três comandos principais. terraform plan compara o código com a realidade e mostra o que faria, sem mexer em nada. terraform apply executa. terraform destroy apaga tudo que o projeto criou. Antes de tudo, terraform init baixa os providers.

Os símbolos de um plano. Leia o plano como leria um diff.

  # aws_s3_bucket.relatorios will be created
  + resource "aws_s3_bucket" "relatorios" {
      + bucket = "loja-relatorios"
    }

  # aws_s3_bucket.dados will be updated in-place
  ~ resource "aws_s3_bucket" "dados" {
      ~ tags = { "ambiente" = "teste" -> "lab" }
    }

  # aws_instance.antiga will be destroyed
  - resource "aws_instance" "antiga" {

  # aws_instance.api must be replaced
-/+ resource "aws_instance" "api" {
      ~ ami = "ami-0aa1" -> "ami-0bb2" # forces replacement

Plan: 2 to add, 1 to change, 2 to destroy.
  • + criar: O recurso não existe e vai ser criado. Valores que só se sabem depois aparecem como (known after apply).
  • ~ alterar: O recurso existe e será ajustado sem ser recriado. A seta mostra valor antigo e novo.
  • - destruir: O recurso sai do código, então vai ser apagado. Leia com atenção: se for um banco, os dados vão junto.
  • -/+ substituir: Algumas mudanças não podem ser feitas no lugar: o recurso é apagado e criado de novo. forces replacement aponta qual atributo causou isso. É o símbolo que mais merece cuidado.
  • Resumo: A linha mais importante. Uma substituição conta duas vezes: uma em “add” e uma em “destroy”. Se você esperava só adicionar e aparece “to destroy”, pare e entenda antes de aplicar.

O ciclo completo no laboratório Docker

Na pasta com o main.tf acima, crie o site, mude a porta e depois apague tudo. Leia cada saída antes de seguir.

  1. Prepare a pasta: baixe o provider do Docker.

    terraform init
    Initializing the backend...
    Initializing provider plugins...
    - Finding kreuzwerker/docker versions matching "~> 3.0"...
    - Installing kreuzwerker/docker v3.0.2...
    
    Terraform has been successfully initialized!
  2. Gere o plano e salve-o no arquivo plano.tfplan, para aplicar exatamente o que você revisou.

    terraform plan -out=plano.tfplan
    Terraform will perform the following actions:
    
      # docker_container.site will be created
      + resource "docker_container" "site" {
          + id    = (known after apply)
          + name  = "site-lab"
          + ports {
              + external = 8080
              + internal = 80
            }
        }
    
      # docker_image.nginx will be created
      + resource "docker_image" "nginx" {
          + name = "nginx:1.27"
        }
    
    Plan: 2 to add, 0 to change, 0 to destroy.
    
    Changes to Outputs:
      + endereco = "http://localhost:8080"
    
    Saved the plan to: plano.tfplan
  3. Aplique o plano salvo.

    terraform apply plano.tfplan
    docker_image.nginx: Creating...
    docker_image.nginx: Creation complete after 6s
    docker_container.site: Creating...
    docker_container.site: Creation complete after 1s [id=4f2a9c71e0b3]
    
    Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
    
    Outputs:
    
    endereco = "http://localhost:8080"
  4. Veja o que mudaria se a porta fosse 9090, passando a variável na linha de comando.

    terraform plan -var="porta=9090"
      # docker_container.site must be replaced
    -/+ resource "docker_container" "site" {
          ~ id   = "4f2a9c71e0b3" -> (known after apply)
            name = "site-lab"
          ~ ports { # forces replacement
              ~ external = 8080 -> 9090 # forces replacement
                internal = 80
            }
        }
    
    Plan: 1 to add, 0 to change, 1 to destroy.
    
    Changes to Outputs:
      ~ endereco = "http://localhost:8080" -> "http://localhost:9090"
  5. Laboratório encerrado: apague tudo que o projeto criou, confirmando automaticamente.

    terraform destroy -auto-approve
    docker_container.site: Destroying... [id=4f2a9c71e0b3]
    docker_container.site: Destruction complete after 1s
    docker_image.nginx: Destroying...
    docker_image.nginx: Destruction complete after 0s
    
    Destroy complete! Resources: 2 destroyed.

Você só queria mudar a porta, e o plano diz Plan: 1 to add, 0 to change, 1 to destroy. O que isso significa?

  • O container vai ser apagado e criado de novo, porque a porta não pode mudar no lugar
  • O Terraform vai criar um segundo container e manter o antigo
  • Deu erro no plano

O estado: a memória do Terraform

O estado fica no arquivo terraform.tfstate. Lá está, por exemplo, que docker_container.site é o container de id 4f2a9c71e0b3. É assim que o plan sabe o que já existe. Se o arquivo some, o Terraform acha que nada existe e tenta criar tudo de novo.

Um trecho de terraform.tfstate

{
  "resources": [
    {
      "type": "docker_container",
      "name": "site",
      "instances": [
        { "attributes": { "id": "4f2a9c71e0b3", "name": "site-lab" } }
      ]
    }
  ]
}

Em equipe, o estado fica num estado remoto (*remote backend*): um lugar compartilhado e protegido, como um bucket com acesso restrito. Junto vem o lock (trava): enquanto alguém roda apply, ninguém mais consegue, para que dois planos não briguem pelo mesmo recurso.

Estado remoto num bucket S3, com trava

terraform {
  backend "s3" {
    bucket       = "loja-terraform-estado"
    key          = "producao/terraform.tfstate"
    region       = "sa-east-1"
    encrypt      = true
    use_lockfile = true
  }
}

Duas pessoas rodam terraform apply ao mesmo tempo, cada uma do seu computador, com o estado guardado só na própria máquina. O que pode acontecer?

  • Cada uma tem uma memória diferente do que existe, e uma pode desfazer ou duplicar o trabalho da outra
  • O Terraform junta as duas mudanças sozinho
  • Nada, porque o provedor de nuvem impede

Quando a realidade foge do código

Drift (desvio) é quando o recurso real deixa de ser igual ao código, quase sempre porque alguém mudou algo direto no console. O próximo plan mostra a diferença e propõe desfazer a mudança manual, para voltar ao que está no código.

Para só enxergar o desvio, sem propor alterações, use terraform plan -refresh-only. Daí você decide: se a mudança manual era certa, leve-a para o código; se não era, rode o apply e deixe o Terraform restaurar.

Durante um incidente, alguém aumentou a memória de um servidor pelo console. Uma semana depois, outra pessoa roda terraform apply para mudar outra coisa. O que acontece com a memória?

Volta para o valor do código, porque o Terraform faz a realidade igual ao arquivo. O servidor pode voltar a sofrer o mesmo problema. Por isso, toda mudança feita na mão numa emergência deve virar um pull request no código logo depois.

Quando um conjunto de recursos se repete (o mesmo site para staging e produção, por exemplo), você o transforma num módulo: uma pasta de arquivos .tf com variáveis de entrada, usada como uma função.

O mesmo módulo usado duas vezes

module "site_staging" {
  source = "./modules/site"
  nome   = "site-staging"
  porta  = 8081
}

module "site_producao" {
  source = "./modules/site"
  nome   = "site-producao"
  porta  = 8080
}

Coloque em ordem uma mudança segura de infraestrutura em equipe.

  • Editar os arquivos .tf numa branch
  • Rodar terraform plan e ler o resumo
  • Abrir um pull request com o plano no comentário
  • Alguém revisa o código e o plano
  • Após o merge, rodar terraform apply com o estado remoto travado

Erros que todo mundo comete uma vez

  • Aplicar sem ler o plano. O apply mostra o plano de novo e pede yes: leia o resumo, sempre.
  • Fazer commit do estado ou de senhas em variáveis. Use variáveis sensíveis (sensitive = true) e um cofre de segredos.
  • Mexer pelo console em recursos do Terraform. Gera drift e a mudança some no próximo apply.
  • Usar -auto-approve em produção. No laboratório, ótimo. Em produção, quem aprova é uma pessoa lendo o plano.
  • Esquecer o destroy no laboratório de nuvem. Recurso esquecido é cobrado todo mês.

O que vai para o repositório Git e o que não vai?

Vai para o Git · Fica fora do Git

  • main.tf e variables.tf
  • terraform.tfstate
  • .terraform.lock.hcl
  • A pasta .terraform/ com os providers baixados
  • Um arquivo .tfvars com a senha do banco
  • A pasta modules/ com seus módulos

Fechamento

  • Infraestrutura como código descreve recursos em arquivos versionados; o Terraform faz a realidade igual ao código.
  • Um arquivo HCL tem provider, resource, variable e output, e referências definem a ordem de criação.
  • plan mostra o que vai mudar com +, ~, - e -/+; apply executa e destroy apaga tudo do projeto.
  • O estado liga o código aos recursos reais, contém segredos, nunca vai para o Git e em equipe fica remoto e com trava.
  • Drift é a realidade diferente do código; módulos reaproveitam conjuntos de recursos.

Crie e apague um recurso por código

Use o laboratório Docker local, sem custo, para viver o ciclo completo do Terraform e documentar o que aprendeu.

  1. Instale o Terraform e crie um main.tf que sobe um container Nginx com a porta numa variável
  2. Rode init, plan e apply e escreva com suas palavras o que o plano dizia
  3. Mude a porta, leia o novo plano e explique por que o container é substituído
  4. Configure o .gitignore para deixar o estado e a pasta .terraform/ fora do repositório
  5. Rode destroy e confirme com docker ps que nada ficou para trás

Referências

Cursos relacionados