Terraform Docker: Um guia completo

Passei um monte de tempo cuidando manualmente dos contêineres Docker nos ambientes de desenvolvimento e produção. Configurações incompatíveis, estados instáveis e incerteza sobre se minha configuração local correspondia à produção atrapalhavam todas as implantações. Quando descobri o provedor Docker do Terraform, tudo mudou.

Neste tutorial, vou te mostrar como integrar o Terraform com o Docker pra criar uma infraestrutura que dá pra reproduzir e controlar as versões. Você vai aprender a provisionar contêineres, gerenciar redes e volumes, implementar restrições de recursos e manter o estado em toda a sua equipe.

Se você está gerenciando servidores de compilação ou organizando microsserviços, pegue seu terminal e vamos transformar a forma como você lida com a infraestrutura do Docker.

Se você é novo no Docker, recomendo começar com nosso curso Introdução ao Docker.

O que é a integração do Terraform com o Docker?

O Terraform é uma ferramenta de infraestrutura como código que gerencia o ciclo de vida dos recursos por meio de um fluxo de trabalho declarativo. Em vez de usar comandos individuais do Docker, você define o estado desejado da infraestrutura nos arquivos de configuração. O Terraform então faz um ciclo de vida de planejar-aplicar-destruir: ele calcula as mudanças necessárias, mostra uma prévia e só aplica depois de aprovadas.

O Terraform Docker provê um servidador que funciona como uma camada de tradução entre o código HashiCorp Configuration Language (HCL) e a API do Docker. Ao escrever resource “docker_container" em uma configuração, o provedor transforma essa declaração nas chamadas apropriadas da API do Docker. Essa abstração significa que os recursos do Docker podem ser gerenciados usando o mesmo fluxo de trabalho usado para a infraestrutura em nuvem.

É aqui que o Terraform é diferente do Docker Compose.

Embora o Compose gerencie contêineres por meio de uma abordagem baseada em projetos usando arquivos YAML, ele não mantém um arquivo de estado que acompanha o que realmente existe. 

Já o Terraform guarda todos os recursos que cria em um terraform.tfstate, o que permite detectar diferenças entre a minha configuração e a realidade. Se alguém mexer manualmente em um contêiner, o Terraform vai perceber e pode restaurá-lo para o estado definido.

Essa abordagem é ótima em vários cenários:

• Para servidores de compilação reproduzíveis, você pode destruir e recriar todo o ambiente com um único comando, garantindo a consistência. 
• Em ambientes de teste, você pode criar uma infraestrutura isolada para cada execução de teste. 
• Para implantações imutáveis, você substitui os contêineres inteiramente, em vez de modificá-los no local, reduzindo os riscos de implantação.

Pré-requisitos e instalação

Antes de mergulhar nas configurações do Terraform, vamos ver se as ferramentas necessárias estão instaladas e configuradas direitinho.

Atender aos requisitos do sistema

Primeiro, veja se o Docker Engine tá funcionando na sua máquina. 

• Linux: Dá uma olhada no docker ps

• macOS ou Windows: Verifique se o Docker Desktop está instalado e funcionando.

O provedor Terraform precisa acessar o daemon Docker, então você precisa confirmar se o seu usuário tem permissão para acessar o soquete Unix em /var/run/docker.sock no Linux ou o pipe nomeado no Windows.

Depois, instale a CLI do Terraform no site oficial da HashiCorp. A instalação do Terraform varia de acordo como sistema operacional:

• Linux: Baixe o pacote certo ou use o gerenciador de pacotes da sua distribuição. 

• macOS: Use o Homebrew. Primeiro, instale o HashiCorp tap usando brew tap hashicorp/tap e, em seguida, instale o Terraform com o comando brew install hashicorp/tap/terraform. 

• Windows: Baixe o binário em hashicorp.com e adicione-o ao seu PATH ou use o Chocolatey: choco install terraform. 

Depois de instalar, dá uma olhada se tá tudo certo rodando o terraform version. 

Com o Docker e o Terraform verificados, o próximo passo é organizar os arquivos do projeto para facilitar a manutenção.

Configurando a estrutura do projeto

Os projetos Terraform se beneficiam de uma abordagem clara e estruturada. Normalmente, eu crio um diretório só para o meu projeto Terraform e começo o controle de versão:

mkdir terraform-docker-project
cd terraform-docker-project
git init

O controle de versão é super importante para a infraestrutura como código. Toda mudança na infraestrutura do Docker deve ser acompanhada, revisada e reversível. Normalmente, eu adiciono o diretório de trabalho e os arquivos de estado do Terraformao arquivoou .gitignore para excluí-los do controle de versão:

.terraform/
*.tfstate
*.tfstate.backup
.terraform.lock.hcl

Por fim, eu crio um arquivo em branco chamado main.tf, onde vou definir minha infraestrutura. Esse arquivo vai guardar a configuração do provedor e as definições dos recursos.

Provedor Terraform Docker e recursos principais

Com a estrutura do projeto pronta, é hora de configurar o provedor Docker e começar a definir os recursos.

Inicializando o provedor Docker

Primeiro, adicionando a configuração do provedor a main.tf:

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

provider "docker" {
  host = "unix:///var/run/docker.sock"
}

O bloco ` required_providers ` diz ao Terraform onde baixar o plugin do provedor. Usar restrições de versão (~> 3.0) permite pequenas atualizações de versão, evitando mudanças significativas. Para hosts Docker remotos, você pode alterar o parâmetro host para algo como tcp://192.168.1.100:2376.

Agora, execute terraform init no diretório raiz do projeto. Isso baixa o plugin do provedor Docker e o guarda em .terraform/providers/. O comando mostra a versão exata instalada, e o Terraform cria um arquivo de bloqueio pra garantir que as versões do provedor sejam consistentes em toda a minha equipe.

Gerenciando imagens de contêiner

Com o provedor inicializado, o próximo passo é definir as imagens do contêiner. Antes de criar contêineres, você precisa gerenciar as imagens que eles usarão, então é preciso definir um recurso de imagem:

resource "docker_image" "nginx" {
  name         = "nginx:1.29"
  keep_locally = true
}

Adicione esse recurso logo depois do bloco do provedor. O parâmetro ` keep_locally ` é importante porque evita que o Terraform remova a imagem quando eu executo ` terraform destroy`. Isso é útil quando vários contêineres compartilham a mesma imagem ou quando eu quero manter as imagens em cache entre as implantações.

Para implantações de produção, fixe as imagens pelo seu resumo SHA256 para garantir a imutabilidade:

resource "docker_image" "nginx" {
 name = "nginx@sha256:b60f25eb5acdd79172de1a289891d9cfe4fc3669daddeeb68619240cbe839d9f"
}

O resumo pode ser obtido no registro de contêineres. Para imagens do Docker Hub como o nginx, você pode encontrá-las no site oficial do Docker, na seção Tags. Usar resumos garante que sempre seja implantado exatamente o mesmo binário da imagem, mesmo que alguém envie umanova imagem com a mesma tag.

Provisionamento de contêineres Docker

Depois que as imagens estiverem definidas, o próximo passo é criar contêineres que as referenciem:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = 8080
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}

A imagem é referenciada usando docker_image.nginx.image_id. Isso cria uma dependência implícita, já que o Terraform só vai tentar criar o contêiner quando a imagem estiver pronta. O bloco “ ports ” mapeia a porta interna 80 do contêiner para a porta 8080 do meu host, o que é igual a docker run -p 8080:80.

As variáveis de ambiente vão na lista env como strings. O Terraform vai recriar o contêiner se algum parâmetro mudar, garantindo que a infraestrutura em execução sempre corresponda à configuração.

Neste ponto, execute terraform plan para ver o que o Terraform irá criar e, em seguida, terraform apply para provisionar a infraestrutura. O Terraform vai criar a imagem e o contêiner. Você pode conferir isso verificando o recurso no Docker Desktop ou executando docker ps no terminal.

Limites de rede, armazenamento e recursos no Terraform

Agora que você tem um contêiner básico funcionando e entende o fluxo de trabalho principal, vamos expandir a infraestrutura com recursos prontos para produção. As próximas seções se baseiam nisso e acrescentam rede, armazenamento persistente e restrições de recursos, tudo essencial para implementações no mundo real.

Gerenciando redes

Para permitir a comunicação entre contêineres e, ao mesmo tempo, manter o isolamento, é essencial criar redes dedicadas. Veja como criar redes isoladas para controlar a conectividade dos contêineres. Adicione o seguinte recurso ao arquivo main.tf:

resource "docker_network" "app_network" {
  name   = "application_net"
  driver = "bridge"
}

Agora, adicione um segundo contêiner que use essa rede. Adicione isso depois do contêiner web:

resource "docker_container" "api" {
  name  = "api-server"
  image = docker_image.nginx.image_id

  networks_advanced {
    name = docker_network.app_network.name
  }
}

Isso cria uma rede de ponte dedicada e conecta o contêiner api a ela. Os contêineres na mesma rede podem se comunicar usando seus nomes de contêiner como nomes de host, o que é perfeito para arquiteturas de microsserviços. 

Verifique o isolamento da rede executando docker network inspect application_net e confirmando que apenas os contêineres pretendidos estão conectados. Certifique-se de executar este comando depois de criar os recursos usando terraform plan e terraform apply.

Com a rede configurada para comunicação entre contêineres, o próximo ponto importante é a persistência dos dados.

Configurando volumes persistentes

Para os dados que precisam continuar funcionando mesmo depois de reiniciar o contêiner, adicione recursos de volume. Coloque isso antes das definições do contêiner:

resource "docker_volume" "db_data" {
  name = "postgres_data"
}

Agora, vamos adicionar um contêiner de banco de dados que usa esse volume:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

 env = [
    "POSTGRES_PASSWORD=mysecretpassword"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}

Volumes gerenciados como esse são criados e controlados pelo Docker, guardados no diretório de dados do Docker. Pra compartilhar arquivos de configuração do host, o usa montagens bind, especificando host_path em vez de volume_name.

volumes {
  host_path      = "/opt/app/config"
  container_path = "/etc/app/config"
  read_only      = true
}

Depois de garantir que os dados sobrevivam à reinicialização dos contêineres, é igualmente importante evitar que um único contêiner monopolize os recursos do sistema.

Definindo restrições de recursos

Além do armazenamento, controlar a quantidade de CPU e memória que cada contêiner pode consumir é fundamental para a estabilidade do sistema. Para evitar que os contêineres usem recursos demais, coloque limites de recursos.

Embora o Docker permita atualizar alguns limites de recursos no local, o modelo declarativo do Terraform geralmente exige a substituição do contêiner para garantir que o estado corresponda à sua configuração. Para evitar tempo de inatividade durante essa substituição, usamos a regra do ciclo de vida “ create_before_destroy ”. 

Importante: Precisamos tirar o argumento fixo name pra evitar conflitos de nomes durante o processo de substituição. Uma opção é usar o argumento ` name_prefix `.

resource "docker_container" "api" {
  name_prefix       = "api-server-"
  image      = docker_image.nginx.image_id
  memory     = 512
  cpu_shares = 1024

  networks_advanced {
    name = docker_network.app_network.name
  }

 lifecycle {
    create_before_destroy = true
  }
}

O parâmetro memory limita a RAM em megabytes. O parâmetro cpu_shares funciona de maneira diferente. É um peso relativo usado quando rola disputa pela CPU. Um contêiner com 1024 compartilhamentos vai ter o dobro do tempo de CPU que um com 512 compartilhamentos, mas só quando o host estiver com carga. 

Para limites rígidos de CPU, você também pode usar cpu_set para fixar contêineres em núcleos específicos da CPU:

cpu_set = "0,1"
}

Confira se essas restrições estão certas executando o comando ` docker inspect background-worker --format='{{.HostConfig.Memory}} {{.HostConfig.CpuShares}} ` e vendo se os valores de Memória e NanoCpus batem com a configuração. 

Mais uma vez, como falado acima, você precisa rodar primeiro o terraform plan e o terraform apply para criar os recursos.

Neste momento, o arquivo main.tf tem a configuração do provedor, uma imagem, uma rede, um volume e três contêineres com várias configurações. 

Variáveis, módulos e segredos no Terraform

À medida que a infraestrutura cresce, os valores codificados se tornam inflexíveis. Essa seção mostra como deixar a configuração reutilizável usando variáveis, módulos e o manuseio adequado de segredos.

Usando variáveis de entrada

O primeiro passo para tornar as configurações flexíveis é extrair valores codificados em variáveis que possam ser facilmente alteradas sem mexer no código principal. Isso pode ser feito criando um novo arquivo chamado variables.tf no mesmo diretório:

variable "web_port" {
  description = "External port for web container"
  type        = number
  default     = 8080

  validation {
    condition     = var.web_port > 1024 && var.web_port < 65535
    error_message = "Port must be between 1024 and 65535."
  }
}

Agora atualize o contêiner web em main.tf para usar essa variável:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = var.web_port
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}

O bloco de validação impede o uso de portas privilegiadas. Para substituir o valor padrão, crie um arquivo terraform.tfvars:

web_port = 9000

Quando você executar o comando ` terraform apply`, o Terraform vai ler os valores desse arquivo automaticamente. Ou então, manda os valores pela linha de comando: terraform apply -var="web_port=9000".

Criando módulos reutilizáveis

As variáveis resolvem o problema dos valores codificados, mas e se você precisar implantar o mesmo padrão completo várias vezes, com todos os seus recursos? 

É aqui que os módulos se destacam. Pense num módulo como um projeto que junta todas essas partes separadas num único pacote, permitindo que você “elimine” toda essa configuração complexa como uma única unidade.

Comece criando uma estrutura de diretórios do módulo:

mkdir -p modules/web-app

Agora, crie o arquivo modules/web-app/variables.tf e adicione o seguinte:

variable "environment" {
  description = "Environment name"
  type        = string
}

variable "port" {
  description = "External port"
  type        = number
}

Depois, crie um arquivo principal modules/web-app/main.tf com este recurso:

resource "docker_container" "app" {
  name  = "app-${var.environment}"
  image = var.image_id

  ports {
    internal = 80
    external = var.port
  }
}

Por fim, crie um arquivo de saída modules/web-app/outputs.tf, que é usado principalmente para mostrar no terminal o valor desejado depois de rodar terraform apply:

output "container_ip" {
  value       = docker_container.app.network_data[0].ip_address
  description = "IP address of the application container"
}

Depois de adicionar as definições do módulo, execute terraform init para instalar os módulos e, em seguida, terraform apply para criar os dois contêineres a partir do mesmo modelo. Você deve conseguir ver todos os recursos no Docker Desktop.

Com padrões de infraestrutura reutilizáveis estabelecidos por meio de módulos, há mais um aspecto crítico do gerenciamento de configuração: o manuseio seguro de informações confidenciais, como senhas e chaves de API.

Tratamento de dados confidenciais

Valores sensíveis, como senhas de bancos de dados, não devem ser codificados de forma rígida. Em vez disso, você pode usar o arquivo variables.tf e definir sensitive = true:

variable "db_password" {
  description = "Database root password"
  type        = string
  sensitive   = true
}

Agora atualize o contêiner do banco de dados em main.tf para referenciar a senha do banco de dados:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

  env = [
    "POSTGRES_PASSWORD=${var.db_password}"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}

Em vez de colocar a senha em terraform.tfvars e codificá-la, defina-a como uma variável de ambiente:

export TF_VAR_db_password="your-secure-password"
terraform apply

A bandeira ` sensitive = true ` impede que o Terraform mostre o valor na saída do console. 

Mas esses valores ficam guardados em texto simples em terraform.tfstate, então, pra garantir que esse arquivo fique seguro, a gente pode protegê-lo usando backends remotos com criptografia. Vamos ver como fazer isso.

Gerenciamento de estado do Terraform e integração com CI/CD

Esta seção fala sobre a mecânica do estado e os fluxos de trabalho de automação que são essenciais para implantações de produção. Mas, antes de implementar a automação, é essencial entender como o Terraform monitora sua infraestrutura por meio do arquivo de estado. 

Entendendo a mecânica dos estados

O estado é a base da capacidade do Terraform de gerenciar infraestrutura. O arquivo ` terraform.tfstate ` mapeia a configuração para IDs reais de contêineres Docker e atributos de recursos. Quando você executa o comando ` terraform apply`, o Terraform compara esse estado com a configuração e calcula as alterações mínimas necessárias.

Dá uma olhada no estado atual com o comando ` terraform show`, que mostra todos os recursos gerenciados. Para as equipes, os arquivos de estado locais criam problemas, conflitos e perda potencial de dados. A solução são os backends remotos.

Para fluxos de trabalho focados no Docker sem infraestrutura em nuvem, o nível gratuito do Terraform Cloud( ) é ideal. Adicione um bloco backend à seção terraform em main.tf:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
  
  backend "remote" {
    organization = "your-org-name"
    
    workspaces {
      name = "docker-infrastructure"
    }
  }
}

Crie umaconta grátisno site do Terraform. Oen, execute terraform login para autenticar com o token fornecido e, em seguida, terraform init para migrar o estado. Isso dá um bloqueio de estado em um espaço de trabalho remoto e colaboração em equipe sem precisar de infraestrutura em nuvem. 

Mas também dá pra criar umbackend remotoem provedores de nuvem,tipo AWS ou GCP.

Automatizando fluxos de trabalho

Com a gestão do estado configurada e guardada remotamente, a infraestrutura está pronta para a colaboração em equipe. A parte final é automatizar o processo de implantação por meio de pipelines de CI/CD, garantindo mudanças consistentes e revisáveis.

Primeiro, crie um .github/workflows/terraform.yml:

name: Terraform Docker Deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        
      - name: Terraform Init
        run: terraform init
        
      - name: Terraform Plan
        if: github.event_name == 'pull_request'
        run: terraform plan
        
      - name: Terraform Apply
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve

Esse fluxo de trabalho executa o terraform plan em cada solicitação pull, mostrando aos revisores quais mudanças de infraestrutura vão rolar. Quando as alterações são mescladas ao main, o terraform apply rola automaticamente, garantindo que toda mudança na infraestrutura passe pelo mesmo processo de revisão que as alterações no código.

Resolução de problemas do Terraform Docker

Mesmo com uma configuração cuidadosa, podem surgir problemas. Entender os problemas comuns e quando pensar em alternativas ajuda a tomar melhores decisões arquitetônicas. 

“Permissão negada”

O erro mais comum no Linux é “permissão negada” ao conectar ao soquete do Docker. Isso rola quando o usuário não tem permissão para acessar /var/run/docker.sock. Resolva isso adicionando o usuário ao grupo docker:

sudo usermod -aG docker $USER

Depois, saia e entre de novo.

Problemas de conectividade WSL2

No Windows com WSL2, surgem problemas de conectividade porque o caminho do soquete é diferente. Verifique se a configuração “Expor daemon em tcp://localhost:2375 sem TLS” do Docker Desktop está ativada e, em seguida, atualize o provedor em main.tf:

provider "docker" {
  host = "tcp://localhost:2375"
}

Falhas na autenticação do registro privado

Para registros Docker privados, adicione autenticação ao bloco do provedor, defina credenciais como variáveis e configure-as por meio de variáveis de ambiente para evitar problemas por causa do hardcoding.

hclprovider "docker" {
  host = "unix:///var/run/docker.sock"
  
  registry_auth {
    address  = "registry.mycompany.com"
    username = var.registry_username
    password = var.registry_password
  }
}

Alternativas ao Terraform

Além da resolução de problemas, é igualmente importante entender quando outras ferramentas podem ser mais adequadas do que o Terraform para o seu caso específico.

Terraform x Kubernetes

O Kubernetes oferece recursos de orquestração bem mais sofisticados : 

• Autocura
• Agendamento avançado
• Descoberta de serviços
• Equilíbrio de carga integrado

Para implantações complexas com vários nós e requisitos de alta disponibilidade, o Kubernetes é a melhor escolha. O Terraform pode provisionar a infraestrutura do Kubernetes, enquanto o Helm ouos manifestos do Kubernetes cuidam da implantação de aplicativos.

Terraform x Ansible

O Ansible é ótimo pra gerenciar configurações dentro de contêineres. Enquanto o Terraform cuida da infraestrutura, o Ansible gerencia a configuração do software e a instalação de pacotes. As duas ferramentas geralmente funcionam juntas: O Terraform cria contêineres Docker e, em seguida, o Ansible configura os aplicativos executados dentro deles.

Terraform vs Docker Compose

Paraambientes de desenvolvimento locais simples, o Docker Compose continua sendo a escolha mais prática. O Terraform é ótimo pra implantações que podem ser repetidas em vários ambientese quando é preciso integrar com outros componentes de infraestrutura.

Pra te ajudar a escolher qual deles pegar, eu resumi asdiferenças mais importantesnesta tabela:

Se você está procurando uma ferramenta pra substituir o Docker, dá uma olhada nonosso guia com as melhores alternativas ao Docker.

Conclusão

Colocar o Docker sob o gerenciamento do ciclo de vida do Terraform transforma as implantações de contêineres de procedimentos manuais em infraestruturas reproduzíveis e controladas por versão. Neste tutorial, mostrei como construir uma infraestrutura completa passo a passo, começando com um provedor e um único contêiner, e depois adicionando rede, armazenamento, variáveis, módulos e automação.

A principal diferença é que o Terraform cuida do provisionamento, criação, atualização e destruição de recursos com base em uma configuração declarativa. A orquestração completa com dimensionamento automático e autocorreção precisa de ferramentas como Kubernetes ou Docker Swarm. O Terraform pode provisionar esses orquestradores, mas não os substitui.

Para os próximos passos, dá uma olhada na documentação oficial do Terraform Registry para o provedor Docker e encontra opções avançadas de recursos, como serviços Docker para Swarm, gerenciamento de segredos e configurações de plug-ins.

Se você quer ter uma experiência prática com contêineres, recomendo se inscrever no nosso programa interativo de Containerização e Virtualização com Docker e Kubernetes.