Homelab Rebuild 2026 — Montando o cluster Proxmox e provisionando com Terraform

Ilustração de um cluster Proxmox provisionado com Terraform

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski

No último post apresentei o plano para reconstruir meu homelab como um pequeno datacenter no estilo corporativo: cinco pilares, oito marcos, um post por marco. O marco 1 é a base sobre a qual todo o resto se apoia — três máquinas físicas transformadas em um único cluster Proxmox VE, mais o módulo Terraform que, de agora em diante, provisiona cada VM em cima dele. Este post cobre as duas coisas. Aviso justo: este projeto inteiro ainda está muito em andamento. Nada aqui está “pronto” ou definitivo — é beta, na melhor das hipóteses, e continua mudando conforme avanço. Trate este post como um retrato de como as coisas estavam quando o escrevi, não como uma montagem concluída.

Índice

🎯 Objetivo deste marco

Duas coisas precisavam estar resolvidas antes que eu pudesse mexer em Active Directory, GitLab ou Kubernetes:

  • Três máquinas HP separadas tinham que virar um cluster Proxmox VE, para que as VMs possam ser gerenciadas, migradas e ter backup a partir de um único painel.
  • Nenhuma VM deveria voltar a nascer na base do clique. Toda VM — do domain controller ao control plane do Kubernetes — é criada por terraform apply, não por um assistente na UI do Proxmox.

Tudo a seguir reflete o cluster como ele realmente roda hoje — puxei os valores ao vivo direto da API do Proxmox em vez de confiar em anotações do dia da instalação.

🖥️ Hardware

Três máquinas HP, propositalmente diferentes entre si — é hardware reaproveitado, não um conjunto casado:

HostRAMArmazenamentoIP de gerenciamento
HP164 GBSSD de SO 512 GB + SSD 2 TB192.168.10.x
HP232 GBSSD de SO 512 GB + SSD 2 TB192.168.10.x
HP332 GBSSD de SO 512 GB + 3×2 TB (ZFS RAIDZ1)192.168.10.x

💽 Instalando o Proxmox VE

Nada de especial na instalação em si: ISO do Proxmox VE 9.2, gravada num pendrive com o Rufus, um pendrive por máquina, boot, instalar, repetir três vezes. Sem mídia virtual remota, sem PXE — para três máquinas na mesma mesa, um pendrive ainda é o caminho mais rápido do zero até um hypervisor rodando. Cada nó recebeu um IP estático na rede de gerenciamento 192.168.10.x/24 durante a instalação (.30, .40, .50 para HP1–HP3), que também é a rede onde ficam o cluster e todas as VMs — mais sobre esse trade-off abaixo. Um passo pós-instalação nos três: trocar os repositórios de pacotes. O Proxmox vem apontado por padrão para o repositório Enterprise, que exige uma assinatura paga para realmente baixar atualizações. Seguindo os passos documentados pelo próprio Proxmox, desativei o repo Enterprise e apontei cada nó para o No-Subscription Repository — ótimo para testes/uso não produtivo, que é exatamente o que um homelab é, só que sem a mesma validação que o repo Enterprise recebe:

# /etc/apt/sources.list.d/proxmox.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

Com isso no lugar, a rodada de sempre nos três nós antes de fazer qualquer outra coisa:

apt-get update
apt-get upgrade
apt-get dist-upgrade

🌐 Rede

Cada nó tem uma única NIC em bridge como vmbr0 (Linux bridge, STP desligado), que é onde o network_device de cada VM vai se conectar depois. Existe uma segunda porta de NIC onboard nas placas, mas ela está sem uso por enquanto — candidata a uma rede dedicada de storage ou corosync no futuro, mas não algo de que um cluster de homelab com 3 nós precise no primeiro dia. Essa é também a única simplificação deliberada que vale destacar: o corosync (o protocolo de heartbeat/quorum do cluster) roda na mesma rede que o tráfego de gerenciamento e das VMs, usando um único ring:

ring0_addr: HP1 = 192.168.10.x
ring0_addr: HP2 = 192.168.10.x
ring0_addr: HP3 = 192.168.10.x

Num cluster de produção você isolaria o corosync em sua própria VLAN ou NICs, para que uma rede de gerenciamento saturada não cause perda de quorum espúria. Para três nós numa rede doméstica sem outro tráfego disputando banda, esse risco é aceitável — está na lista de coisas a revisitar se isso um dia crescer além de um homelab. Se você algum dia tiver perda de quorum espúria, o RackNotes tem um passo a passo completo sobre a matemática dos votos, modos de falha do Corosync, QDevice e caminhos de recuperação: Proxmox cluster quorum loss.

🔗 Formando o cluster

Fluxo padrão do pvecm: criar o cluster no HP1 e depois juntar HP2 e HP3 a ele. Com três membros votantes, o cluster tolera exatamente um nó offline (2 de 3 votos) antes de perder o quorum — o setup mínimo viável de HA, e o motivo de ter ido com três nós em vez de dois. Consultando o cluster hoje, dá para confirmar que o caminho feliz se manteve:

$ pvecm status
Cluster name:   homelab
Quorate:        Yes
Nodes:          3

Nodeid  Ip              Name
1       192.168.10.x   HP1 (local)
2       192.168.10.x   HP2
3       192.168.10.x   HP3

🗄️ Layout de armazenamento

É aqui que os três nós deixam de ser idênticos. O segundo disco de cada nó (ou discos, no caso do HP3) foi configurado de forma diferente de propósito:

  • HP1 & HP2: o SSD extra de 2 TB é adicionado como directory storage simples (data / data-hp2) — sem ZFS, sem RAID, só um sistema de arquivos para discos de VM, ISOs e backups. Um único SSD, nada com que espelhar, então a opção mais simples vence.
  • HP3: três discos de 2 TB vão para um pool ZFS em RAIDZ1 (data-hp3), resultando em pouco menos de 4 TB utilizáveis com tolerância a falha de um disco. Esse é o nó reservado para tudo o que eu não quero perder por causa de um único disco morto — pense em réplicas do Longhorn ou dados do MinIO quando o Kubernetes chegar.

Cada nó também mantém o storage padrão local (sistema de arquivos raiz) e local-lvm (LVM-thin no SSD do SO) criado pelo instalador, usado para o próprio SO e como reserva.

🧱 De ClickOps para Infrastructure as Code

Com o cluster no ar, o próximo passo tentador é clicar em “Create VM” sete vezes na UI do Proxmox. Fiz exatamente isso na versão anterior deste homelab, e cada VM acabou ligeiramente diferente — uma configuração de cloud-init esquecida aqui, um IP estático digitado à mão ali, nenhum registro do que eu tinha realmente feito seis meses depois. Desta vez não: cada VM desta reconstrução é definida uma vez, no Terraform, e reproduzível a partir de um cluster limpo.

⚙️ O módulo Terraform

O módulo fica em 01_terraform/ no repositório do projeto e usa o provider bpg/proxmox. Em vez de montar uma ISO do Ubuntu Server e clicar pelo instalador, cada VM é clonada de uma cloud image do Ubuntu 26.04 e configurada inteiramente via cloud-init — IP estático, DNS, chave SSH, tudo — então não há etapa de instalação interativa em lugar nenhum do pipeline:

resource "proxmox_download_file" "ubuntu_cloud_image" {
  content_type = "iso"
  datastore_id = var.image_datastore_id
  node_name    = var.proxmox_node
  url          = var.ubuntu_cloud_image_url
  file_name    = "noble-server-cloudimg-amd64.img"
  overwrite    = false
}

resource "proxmox_virtual_environment_vm" "vm" {
  for_each = local.vms

  name        = each.key
  tags        = ["terraform", "rebuild-2026"]
  node_name   = var.proxmox_node
  vm_id       = each.value.vmid

  disk {
    datastore_id = var.vm_datastore_id
    file_id      = proxmox_download_file.ubuntu_cloud_image.id
    interface    = "scsi0"
    size         = each.value.disk_gb
  }

  initialization {
    ip_config {
      ipv4 {
        address = "${each.value.ip}/${var.network_prefix}"
        gateway = var.network_gateway
      }
    }
    user_account {
      username = var.vm_username
      keys     = var.ssh_public_keys
    }
  }
}

Todas as sete VMs — uma por papel neste marco — são declaradas num único mapa locals.vms, então adicionar uma oitava VM depois é um diff de cinco linhas, não um bloco de resource copiado e colado:

NomePapelIPRAMDisco
HP1-dc01AD / DNS / Root CA192.168.10.x4 GB60 GB
HP1-gitlab01GitLab / Container Registry192.168.10.x8 GB120 GB
HP1-seed01VM de dev (Ansible, kubectl, ferramentas)192.168.10.x4 GB60 GB
HP1-vault01Gerenciamento de segredos (fase 2)192.168.10.x2 GB40 GB
HP1-icinga01Monitoramento192.168.10.x4 GB60 GB
HP1-k8s-cp01Control plane RKE2192.168.10.x8 GB80 GB
HP1-k8s-cp02Control plane RKE2192.168.10.x8 GB80 GB

Os IDs das VMs seguem 100 + <último octeto do IP> (131–137) — o Proxmox exige IDs ≥ 100, e assim o ID e o endereço continuam fáceis de correlacionar de relance, sem uma tabela de consulta separada.

▶️ Colocando no ar

O rollout inteiro são três comandos, uma vez que um token de API do Proxmox e uma chave SSH estejam prontos:

cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: API URL, API token, node name, SSH key

terraform init
terraform plan
terraform apply

Alguns minutos depois, as sete VMs existem, dão boot e respondem nos IPs atribuídos — e o Terraform diz exatamente qual é qual:

Outputs:

vm_ids = {
  "HP1-dc01"     = 131
  "HP1-gitlab01" = 132
  "HP1-icinga01" = 135
  "HP1-k8s-cp01" = 136
  "HP1-k8s-cp02" = 137
  "HP1-seed01"   = 133
  "HP1-vault01"  = 134
}
vm_ips = {
  "HP1-dc01"     = "192.168.10.x"
  "HP1-gitlab01" = "192.168.10.x"
  ...
}

🧩 Algumas coisas que vale destacar

  • Cloud image, não ISO. A ISO do Ubuntu no storage local do HP1 não é usada por este módulo de propósito — clonar uma cloud image e configurá-la via cloud-init é mais rápido e totalmente desassistido. A ISO fica por aí só para a rara instalação manual.
  • ignore_changes no file_id do disco. Sem isso, o Terraform quer reimportar a imagem base a cada plan, já que o ID do arquivo baixado não foi feito para ser reconciliado depois do clone inicial.
  • Segredos nunca saem do repositório interno. O terraform.tfvars guarda o token de API real e a chave SSH e está no gitignore; um hook de pre-push bloqueia ativamente que ele chegue ao espelho público deste projeto no GitHub, além do gitignore.
  • O state é local, e tudo bem. Um operador, um notebook rodando apply — um backend remoto estaria resolvendo um problema que eu ainda não tenho.

Para um passo a passo técnico mais aprofundado do módulo — arquitetura, cada variável, o inventário completo de VMs e uma lista contínua de lições aprendidas — veja 01_terraform/docs/ no repositório (em inglês, alemão e francês).

⚠️ Este projeto inteiro — incluindo o código Terraform mostrado abaixo — é um trabalho permanentemente em andamento. Ele roda, faz o que promete, mas ainda é beta e é retrabalhado o tempo todo. Não trate nada aqui como pronto ou estável.

📊 O ponto cego do ballooning no Windows

A HP1-dc01 é provisionada por este módulo como qualquer outra VM, mas não fica Ubuntu por muito tempo — ela é convertida para Windows Server logo em seguida, já que é disso que o Active Directory precisa. No momento em que isso aconteceu, o gráfico de RAM dela no resumo do Proxmox travou em 100% dos 4 GB atribuídos, não importa o quão ociosa a VM estivesse de fato. A causa: o Proxmox não mede o uso de memória do guest diretamente. Ele lê esse valor do dispositivo virtual de balloon do QEMU, que só reporta números reais se houver um driver rodando dentro do guest para alimentá-lo. Nas VMs Linux deste cluster, isso vem junto com o qemu-guest-agent — já coberto na correção do guest agent acima. O Windows Server não tem nada equivalente embutido, então sem software extra o dispositivo de balloon não tem nada para reportar, e o Proxmox simplesmente mostra a VM cravada na alocação total. A correção foi um segundo CD-ROM virtual: montar a ISO de drivers virtio-win e instalar o VirtIO Balloon Driver a partir dela pelo Gerenciador de Dispositivos. É o mesmo pacote de drivers que também traz o equivalente Windows do guest agent — depois de instalado, o gráfico do resumo passou a acompanhar a pressão real de memória em vez de uma linha reta no teto. Mais sobre transformar esta VM num domain controller de verdade no próximo post.

🔜 O que vem a seguir

Com um cluster de 3 nós com quorum e uma forma repetível de subir VMs, o marco 2 começa a transformar a HP1-dc01 num domain controller de verdade: Active Directory, DNS e a Root CA offline em que tudo o mais neste homelab vai acabar confiando. Esse é o próximo post.

Interface web do Proxmox VE mostrando o cluster de homelab com três nós

📚 Mais nesta série: Homelab Rebuild 2026

Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes