Automação GitOps com Terraform e Proxmox
Source: Dev.to
O problema inicial
Sempre que eu precisava criar uma VM no Proxmox, o processo se repetia: abrir a interface web, preencher formulários, configurar rede manualmente, aguardar a criação da VM, acessar via SSH e configurar o ambiente.
Além disso, era necessário torcer para lembrar exatamente quais passos haviam sido executados caso fosse preciso replicar o processo no futuro. Não havia histórico de mudanças, automação consistente ou rastreabilidade.
Mesmo utilizando scripts ou o próprio Terraform, ainda existiam etapas manuais, tornando o processo mais demorado do que deveria e com pontos claros de melhoria.
A solução: GitOps + Terraform + GitHub Actions
Implementei um fluxo completo de GitOps, no qual toda a infraestrutura passou a ser gerenciada exclusivamente por código versionado em Git.
O resultado foi bastante expressivo: hoje consigo criar, modificar ou remover VMs simplesmente realizando um commit e um push. Em cerca de dois a três minutos, a alteração é automaticamente aplicada no ambiente Proxmox.
O que aprendi no caminho
Nem tudo é simples, especialmente para quem está começando do zero.
Como já possuo uma boa experiência com essas ferramentas, configurar corretamente as permissões no Proxmox, implementar um self‑hosted runner na rede local (já que o Proxmox não é acessível diretamente da nuvem) e estruturar o código de forma escalável e reutilizável não foi algo particularmente difícil.
Ainda assim, cada etapa se mostrou uma oportunidade de aprendizado e de refinamento dos processos relacionados a Infrastructure as Code, CI/CD e boas práticas de automação.
Observação: para quem nunca fez algo semelhante, deixei um passo a passo detalhado, além de uma FAQ, para facilitar a reprodução do ambiente.
Tecnologias utilizadas
- Terraform – IaC
- GitHub Actions – automação CI/CD
- Terraform Cloud (HCP Terraform) – gerenciamento remoto de estado
- Proxmox – hypervisor
- Self‑hosted runners – execução de jobs localmente
Todas as ferramentas são 100 % open source e gratuitas, rodando em um ambiente self‑hosted que garante controle total sobre os dados e a infraestrutura.
O impacto real
| Antes | Agora |
|---|---|
| 15–20 minutos por VM (processo manual, sujeito a erros, sem histórico) | ~30 segundos para definir a VM em código, commit e push automáticos, com rastreabilidade completa via Git |
Mais importante que o tempo economizado foi o ganho em confiabilidade. Cada mudança passa por revisão, fica registrada no histórico do Git e pode ser revertida facilmente com um simples git revert. Isso é especialmente valioso em ambientes de experimentação, onde a possibilidade de voltar atrás com segurança faz toda a diferença.
Lições aprendidas
- Automação não é sobre eliminar todo o trabalho manual, mas sim reduzir tarefas repetitivas e propensas a erros.
- Infrastructure as Code não é exclusiva de grandes empresas; homelabs são ambientes ideais para experimentação.
- Documentação é tão importante quanto o código – dediquei tempo a documentar cada etapa pensando no meu “eu do futuro”.
- Self‑hosted runners ampliam significativamente as possibilidades de automação em ambientes locais.
Próximos passos / Melhorias
Pretendo evoluir esse projeto integrando o Ansible, já que atualmente utilizo o Semaphore UI para a configuração pós‑criação das VMs, além de adicionar testes automatizados antes do deploy.
Para quem se interessou pelos detalhes técnicos da implementação e quiser reproduzir o projeto, o passo a passo (incluindo troubleshooting de todos os problemas enfrentados) está disponível em: homelab-infrastructure-template.