Clicar em um console de nuvem é adequado para um servidor. Ele falha quando você precisa da mesma configuração na preparação e na produção, ou quando alguém pergunta quem alterou uma regra de firewall em março passado. Este tutorial do Terraform para iniciantes mostra uma maneira melhor: descrever sua infraestrutura em código e deixar uma ferramenta torná-la real.

A maioria dos tutoriais começa com uma conta na nuvem, o que aumenta o risco de cobrança antes que você aprenda alguma coisa. Começamos com o provedor do Terraform local, que apenas cria arquivos no seu computador, então erros não custam nada. Esses exemplos e o resultado da amostra são ilustrações padrão que não executamos para este artigo, e o texto exato varia de acordo com a versão.

O que é Terraforma?

Terraform é uma ferramenta de infraestrutura como código (IaC) da HashiCorp. Você escreve arquivos de configuração em HCL, a linguagem de configuração HashiCorp, descrevendo o resultado final desejado. O Terraform então decide o que criar, alterar ou excluir para chegar lá.

Ele se comunica com plataformas por meio de plug-ins chamados provedores. Existem provedores para AWS, Azure, Google Cloud, Kubernetes, GitHub, Cloudflare e muitos outros, então você pode usar um fluxo de trabalho para todos eles.

Uma coisa a saber: em 2023, a HashiCorp mudou o Terraform para a Business Source License. A comunidade então criou o OpenTofu, um fork de código aberto que usa comandos e configurações muito semelhantes. O que você aprende aqui se aplica amplamente a ambos.

Por que infraestrutura como código?

Terraform também é declarativo. Você afirma “deveria haver três servidores”, não “criar um servidor três vezes”. Se já existirem dois, ele adiciona um. Um script que simplesmente repete seus passos pode acabar criando mais três.

Instale o Terraform

Instale-o usando as instruções oficiais da HashiCorp para o seu sistema operacional e confirme se funciona:

terraform -version

Crie uma pasta vazia para o projeto. O Terraform lê cada arquivo .tf na pasta atual, portanto, uma pasta equivale a uma configuração.

Sua primeira configuração

Crie um arquivo chamado main.tf:

terraform {
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

resource "local_file" "greeting" {
  filename = "${path.module}/hello.txt"
  content  = "Hello from Terraform\n"
}

Observe o bloco resource, pois quase tudo que você escreve segue esse formato. local_file é o tipo de recurso e greeting é o seu próprio nome dentro da configuração. Juntos, eles formam seu endereço: local_file.greeting. Os argumentos internos descrevem o que você deseja.

O fluxo de trabalho: iniciar, planejar, aplicar

inicialização do terraform

Isso prepara a pasta e baixa os provedores solicitados. Execute-o uma vez no início e novamente sempre que adicionar um provedor ou módulo. Ele também cria um arquivo .terraform.lock.hcl, que registra versões exatas do provedor. Envie esse arquivo para o Git.

terraform init

plano de terraformação

Isso compara seu código com o que existe e mostra as alterações planejadas, sem mexer em nada:

terraform plan

# local_file.greeting will be created
+ resource "local_file" "greeting" {
    + content  = "Hello from Terraform\n"
    + filename = "./hello.txt"
  }

Plan: 1 to add, 0 to change, 0 to destroy.

Aprenda os símbolos, pois você lerá muitos planos:

aplicar terraform

Isso mostra o plano novamente, pede confirmação e faz as alterações:

terraform apply

Digite yes e hello.txt aparecerá. Agora execute terraform plan novamente. Não deve reportar nenhuma alteração, pois a realidade já corresponde ao seu código. Esta propriedade, onde executá-la repetidamente não causa mais alterações, é chamada de idempotência.

Mudando e destruindo

Edite a linha content e execute terraform plan. Terraform identifica a diferença e propõe uma mudança. Para este recurso, ele substitui o arquivo. Preste atenção às substituições em infraestruturas reais, pois recriar um banco de dados pode significar perda de dados.

Em seguida, exclua hello.txt manualmente e planeje novamente. Terraform percebe que está faltando e se oferece para recriá-lo. Uma diferença entre o seu código e a realidade é chamada de desvio, e detectá-la é um dos principais benefícios da ferramenta.

Para remover tudo o que esta configuração gerencia, execute:

terraform destroy

Variáveis e resultados

Os valores codificados impedem que você reutilize o código. Variáveis de entrada tornam uma configuração flexível e as saídas reportam valores úteis:

# variables.tf
variable "environment" {
  type        = string
  description = "Deployment environment"
  default     = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Use dev, staging or prod."
  }
}

# main.tf
resource "local_file" "config" {
  filename = "${path.module}/${var.environment}.txt"
  content  = "environment=${var.environment}\n"
}

# outputs.tf
output "config_path" {
  value = local_file.config.filename
}

Defina valores na linha de comando ou mantenha-os em um arquivo chamado terraform.tfvars, que é carregado automaticamente:

terraform apply -var="environment=staging"

Usar local_file.config.filename na saída também é como os recursos se referem uns aos outros. O Terraform lê essas referências para descobrir a ordem correta de criação das coisas.

Estado do Terraform

Após a inscrição, você encontrará um arquivo chamado terraform.tfstate. Este é o registro do Terraform sobre o que ele gerencia, mapeando seu código para objetos reais. Sem ele, o Terraform não saberia que local_file.greeting é aquele arquivo específico.

Três regras são importantes aqui:

1. Nunca confirme o estado no Git. Ele pode conter senhas e outros segredos em texto simples.
2. Não edite manualmente. Use comandos como terraform state list e terraform state mv.
3. Use um back-end remoto para projetos de equipe. Um back-end compartilhado armazena o estado centralmente e o bloqueia, de forma que duas pessoas não possam se inscrever ao mesmo tempo.

Aqui está um back-end típico usando Amazon S3, com um bucket que você cria antecipadamente:

terraform {
  backend "s3" {
    bucket       = "my-company-terraform-state"
    key          = "shop/prod/terraform.tfstate"
    region       = "ap-south-1"
    encrypt      = true
    use_lockfile = true
  }
}

Um verdadeiro recurso de nuvem

O fluxo de trabalho não muda quando você muda para uma nuvem. Aqui está um bucket S3 na AWS. Verifique primeiro os preços e destrua tudo o que você criar enquanto pratica:

provider "aws" {
  region = "ap-south-1"
}

resource "aws_s3_bucket" "reports" {
  bucket = "my-unique-reports-bucket-2026"

  tags = {
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

O Terraform obtém credenciais da configuração da AWS CLI ou de variáveis de ambiente. Nunca escreva chaves de acesso em um arquivo .tf.

Módulos

Um módulo é simplesmente uma pasta de arquivos Terraform que você pode chamar com diferentes entradas. Funciona como uma função, permitindo definir um padrão uma vez e reutilizá-lo:

project/
  main.tf
  modules/
    reports_bucket/
      main.tf
      variables.tf
      outputs.tf

module "staging_reports" {
  source      = "./modules/reports_bucket"
  environment = "staging"
}

module "prod_reports" {
  source      = "./modules/reports_bucket"
  environment = "prod"
}

O Terraform Registry público também possui módulos prontos, mas leia-os antes de confiar neles e fixe a versão. Não construa módulos muito cedo. Espere até ter repetido um padrão pelo menos duas vezes.

Um fluxo de trabalho de equipe seguro

1. Crie uma ramificação e altere os arquivos .tf. Consulte nosso tutorial do Git para iniciantes se precisar de uma atualização.
2. Execute terraform fmt e terraform validate.
3. Abra uma solicitação pull, com a saída de terraform plan anexada para revisão.
4. Após a aprovação, aplique o plano salvo em um local controlado, de preferência um pipeline.

Salvar o plano garante que você aplique exatamente o que foi revisado:

terraform plan -out=tfplan
terraform apply tfplan

Isso se encaixa naturalmente em CI/CD e GitHub Actions. O Terraform geralmente provisiona o cluster, e ferramentas como o Kubernetes executam aplicativos sobre ele.

Erros comuns

• Inscrever-se sem ler o plano. Um -/+ em um banco de dados pode ser uma surpresa muito cara.
• Manter o estado em um laptop. Perca esse laptop e o Terraform perderá o controle de sua infraestrutura.
• Fazendo alterações manuais no console. Elas causam desvios e a próxima aplicação pode desfazê-las.
• Usando versões não fixadas. Fixe as versões do provedor e do módulo para que as atualizações aconteçam propositalmente.
• Usar uma configuração enorme. A divisão por ambiente ou sistema limita os danos de qualquer erro.

Considerações finais

Você já viu as ideias por trás de quase todo o trabalho do Terraform: declarar recursos, revisar o plano, aplicá-lo e proteger o estado. Pratique com o provedor local até que o fluxo de trabalho pareça natural e, em seguida, gerencie um pequeno recurso real em uma conta de nível gratuito. Traga estados e módulos remotos quando mais de uma pessoa ou mais de um ambiente estiver envolvido.

Perguntas frequentes

Continue aprendendo