Terraform e Ansible no Proxmox: infraestrutura como código no seu cluster

Criar VM pelo painel do Proxmox é rápido e agradável. O problema não é a primeira VM — é a trigésima, criada por três pessoas diferentes, cada uma com um ajuste sutilmente distinto de disco, de rede ou de tipo de CPU. Seis meses depois, ninguém sabe por que a VM 114 se comporta diferente da 115, e a resposta está enterrada no histórico de cliques que não existe.

Infraestrutura como código resolve isso, e o Proxmox suporta bem os dois caminhos principais. A confusão frequente é achar que Terraform e Ansible competem — eles ocupam etapas diferentes do mesmo processo.

A divisão de trabalho

A regra que funciona: Terraform cuida do que o Proxmox conhece; Ansible cuida do que está dentro da VM.

Dá para fazer tudo com Ansible — ele tem módulos para criar VM no Proxmox. E dá para fazer muita coisa com Terraform e cloud-init. A divisão acima é a que produz código mais legível e menos surpresa.

A base de tudo: um template bem feito

Antes de escrever uma linha de código, você precisa de um template. Sem ele, o provisionamento vira instalação de sistema operacional automatizada, que é lenta, frágil e desnecessária.

O template correto tem:

• Imagem de nuvem da distribuição, que já vem preparada para cloud-init.
• Agente de convidado instalado — é o que permite ao Proxmox saber o endereço IP da VM, congelar o sistema de arquivos no backup e desligar graciosamente. Sem ele, o Terraform frequentemente não descobre o endereço da máquina que acabou de criar.
• Drivers VirtIO para disco e rede.
• Disco pequeno, que será expandido no clone. É mais fácil crescer que encolher.
• Sem chave SSH, sem senha, sem identificador de máquina fixo — tudo isso é injetado no clone pelo cloud-init.
• Convertido em template de fato, não deixado como VM desligada.

Um template por distribuição e versão suportada. Regenerados periodicamente com as atualizações já aplicadas, para que a VM nova não nasça com trinta pacotes desatualizados.

Esse último ponto costuma virar um pipeline próprio: uma tarefa mensal que constrói os templates atualizados e os publica. Vale o investimento.

Terraform no Proxmox

O provider da comunidade é o caminho usual, e há mais de um em circulação — vale escolher um que esteja ativo e ficar nele, porque a sintaxe difere entre eles.

O que o Terraform resolve bem:

• Clonagem do template com os parâmetros que você define.
• Configuração de cloud-init: usuário, chaves SSH, endereço IP, gateway, DNS.
• Rede: qual bridge, qual VLAN.
• Disco: tamanho, storage de destino.
• Ciclo de vida: criar, alterar e destruir de forma reproduzível.

O que exige cuidado:

O estado. O Terraform guarda um arquivo com o que ele criou, e esse arquivo é a fonte da verdade dele. Se ele se perder, o Terraform não sabe mais o que gerencia. Se duas pessoas rodarem ao mesmo tempo sobre o mesmo estado, o resultado é imprevisível.

Guarde o estado em backend remoto com travamento — não no laptop de alguém, não no repositório. E trate-o como dado sensível: ele contém informação da infraestrutura e, por vezes, valores que você preferia não expor.

Mudanças manuais no painel. Se alguém ajusta pelo painel uma VM gerenciada pelo Terraform, o próximo comando vai querer desfazer o ajuste. Isso não é defeito, é o propósito — mas precisa estar combinado com a equipe. Recurso gerenciado por código não se altera pelo painel.

Recriação inesperada. Alguns atributos, quando alterados, exigem destruir e recriar a VM. Sempre revise o plano antes de aplicar, especialmente em produção. O plano avisa; quem não lê, descobre depois.

Token de API, nunca senha. Com privilégio separado e escopo mínimo: o necessário para criar VM no pool e no storage que aquele código gerencia, e nada além.

Ansible no Proxmox

O Ansible entra depois que a VM existe — e também resolve bem o próprio hipervisor.

Dentro das VMs: instalar e configurar aplicação, ajustar serviços, aplicar hardening, gerenciar usuários. O inventário dinâmico é o recurso que mais economiza trabalho: em vez de manter uma lista de máquinas na mão, o Ansible consulta o Proxmox e monta o inventário a partir do que existe, com agrupamento por pool, por tag ou por nó.

Isso significa que uma VM criada pelo Terraform aparece automaticamente para o Ansible, sem passo intermediário.

No hipervisor: configuração dos nós, pacotes, rede, parâmetros do sistema, usuários do Proxmox, configuração de backup. É o que garante que o nó novo do cluster fique idêntico aos existentes — outra fonte clássica de comportamento divergente.

Um cuidado: automação no hipervisor é poderosa e perigosa. Um playbook mal escrito rodando em todos os nós ao mesmo tempo derruba o cluster. Limite a execução a um nó por vez em qualquer tarefa que reinicie serviço.

O caminho completo

Como as peças se encaixam em uma operação madura:

1. Pipeline mensal constrói os templates atualizados.
2. Terraform cria as VMs a partir do template, com cloud-init injetando usuário, chaves e rede.
3. Cloud-init deixa a VM acessível por SSH na primeira inicialização.
4. Ansible descobre a VM pelo inventário dinâmico e aplica a configuração da função dela.
5. Ansible periódico reaplica a configuração, corrigindo divergência.
6. Terraform destrói quando a VM não é mais necessária, sem deixar sobra.

Tudo em repositório, com revisão em pull request e histórico. A pergunta "por que essa VM tem 8 GB?" passa a ter resposta: está no commit, com autor, data e justificativa.

O que o código traz além da velocidade

Velocidade é o argumento óbvio e o menos importante. Os ganhos que realmente mudam a operação:

• Reprodutibilidade. Ambiente de homologação idêntico ao de produção, porque nasce do mesmo código com parâmetros diferentes.
• Revisão. Mudança de infraestrutura passa por outra pessoa antes de acontecer.
• Histórico. O que mudou, quando, por quem e por quê.
• Reversão. Voltar ao commit anterior e aplicar.
• Documentação viva. O código é a descrição do ambiente, e não desatualiza como um documento.
• Recuperação de desastre. Reconstruir o ambiente é aplicar o código. Isso transforma DR de projeto em procedimento — desde que os dados venham do backup.

Esse último item é o de maior valor e o menos lembrado na hora de justificar o investimento.

Por onde começar

Adotar tudo de uma vez costuma falhar. A sequência que funciona:

1. Um template bom, com agente de convidado e cloud-init. Já resolve metade da inconsistência.
2. Terraform para ambientes novos apenas. Não tente importar o legado no começo.
3. Ansible para uma função simples — um servidor web, por exemplo — e expanda.
4. Inventário dinâmico ligando as duas ferramentas.
5. Pipeline aplicando o código, em vez de execução no laptop.
6. Importação gradual do que já existe, quando o time estiver confortável.

Importar ambiente legado é a parte mais trabalhosa e a de menor retorno imediato. Deixe por último, e considere simplesmente recriar o que for barato recriar.

Erros comuns

• Começar sem template, automatizando instalação de sistema operacional.
• Template sem agente de convidado, e o Terraform não descobre o endereço da VM.
• Estado do Terraform local, no laptop ou no repositório.
• Estado sem travamento, com duas pessoas aplicando ao mesmo tempo.
• Alterar pelo painel uma VM gerenciada por código.
• Aplicar sem ler o plano e recriar VM de produção sem querer.
• Usar senha de usuário em vez de token de API com escopo mínimo.
• Playbook reiniciando serviço em todos os nós do cluster ao mesmo tempo.
• Segredos no repositório em vez de cofre.
• Tentar importar todo o legado antes de provar o fluxo em algo novo.
• Template nunca atualizado, com VMs nascendo desatualizadas.
• Rodar o Terraform manualmente e não ter histórico de quem aplicou o quê.

Onde a Solvefy/Cloud entra

Como parceiros oficiais Proxmox, implantamos esse fluxo de ponta a ponta: pipeline de construção de templates com agente de convidado e cloud-init, módulos Terraform para os seus padrões de VM, papéis Ansible por função, inventário dinâmico ligando as duas pontas, estado remoto com travamento, tokens com escopo mínimo e a aplicação por pipeline com revisão. Também fazemos a transferência de conhecimento para o seu time — porque automação que só uma pessoa entende é um novo ponto único de falha.

Suas VMs ainda nascem por clique? Fazemos um diagnóstico gratuito da infraestrutura, sem compromisso, em solvefy.cloud.

Solvefy/Cloud — Infraestrutura que cresce com você.