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,variableeoutputnum arquivo HCL - Rodar
init,plan,applyedestroye 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.0aceita 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çodocker_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 replacementaponta 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.
Prepare a pasta: baixe o provider do Docker.
terraform initInitializing the backend... Initializing provider plugins... - Finding kreuzwerker/docker versions matching "~> 3.0"... - Installing kreuzwerker/docker v3.0.2... Terraform has been successfully initialized!Gere o plano e salve-o no arquivo
plano.tfplan, para aplicar exatamente o que você revisou.terraform plan -out=plano.tfplanTerraform 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.tfplanAplique o plano salvo.
terraform apply plano.tfplandocker_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"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"Laboratório encerrado: apague tudo que o projeto criou, confirmando automaticamente.
terraform destroy -auto-approvedocker_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
.tfnuma branch - Rodar
terraform plane 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 applycom o estado remoto travado
Erros que todo mundo comete uma vez
- Aplicar sem ler o plano. O
applymostra o plano de novo e pedeyes: 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-approveem produção. No laboratório, ótimo. Em produção, quem aprova é uma pessoa lendo o plano. - Esquecer o
destroyno 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.tfevariables.tfterraform.tfstate.terraform.lock.hcl- A pasta
.terraform/com os providers baixados - Um arquivo
.tfvarscom 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,variableeoutput, e referências definem a ordem de criação. planmostra o que vai mudar com+,~,-e-/+;applyexecuta edestroyapaga 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.
- Instale o Terraform e crie um
main.tfque sobe um container Nginx com a porta numa variável - Rode
init,planeapplye escreva com suas palavras o que o plano dizia - Mude a porta, leia o novo plano e explique por que o container é substituído
- Configure o
.gitignorepara deixar o estado e a pasta.terraform/fora do repositório - Rode
destroye confirme comdocker psque nada ficou para trás