Criar cluster Ku­ber­ne­tes no Proxmox: guia passo a passo

A criação de um cluster Ku­ber­ne­tes no Proxmox permite operar, em um ambiente vir­tu­a­li­zado e auto-hospedado, uma pla­ta­forma de or­ques­tra­ção de con­têi­ne­res de alto de­sem­pe­nho. Isso é ideal para ambientes de teste, fluxos de trabalho de de­sen­vol­vi­mento e CI, ou também para cenários menores de produção. Neste guia, você vai aprender passo a passo como con­fi­gu­rar máquinas virtuais no Proxmox e, a partir delas, montar um cluster Ku­ber­ne­tes estável.

Passo 1: verificar os pré-re­qui­si­tos

Antes de iniciar a con­fi­gu­ra­ção do cluster Ku­ber­ne­tes, você deve garantir que seu ambiente atenda a todos os pré-re­qui­si­tos técnicos. Uma base bem-preparada economiza muito tempo depois e evita erros de con­fi­gu­ra­ção.

Você precisa, primeiro, de uma ins­ta­la­ção funcional do Proxmox VE. Por motivos de de­sem­pe­nho, recomenda-se uma ins­ta­la­ção bare-metal do Proxmox. Tanto o acesso via web pela interface do Proxmox quanto o acesso via SSH à linha de comando devem estar dis­po­ní­veis. Via SSH, você pode executar comandos, fazer upload de imagens e au­to­ma­ti­zar con­fi­gu­ra­ções.

Para um cluster Ku­ber­ne­tes estável, você também precisa de várias máquinas virtuais. Recomenda-se os seguintes nós do Ku­ber­ne­tes:

• um nó mestre (para a chamada control plane) e
• pelo menos dois nós worker.

Assim, você obtém um certo nível de re­dun­dân­cia e pode operar o Ku­ber­ne­tes da forma como é previsto em ambientes de produção reais. Para fins de teste, porém, uma con­fi­gu­ra­ção menor com um nó mestre e um nó worker também é su­fi­ci­ente.

Seu host Proxmox também deve ter uma interface de bridge funcional, que permita às máquinas virtuais o acesso à rede local e, se ne­ces­sá­rio, à internet. Isso é im­por­tante para que as VMs possam baixar atu­a­li­za­ções e instalar com­po­nen­tes do Ku­ber­ne­tes pos­te­ri­or­mente.

Etapa 2: baixar a imagem cloud e prepará-la como template

Ins­ta­la­ções do Ku­ber­ne­tes podem ser feitas com mais fa­ci­li­dade usando os chamados cloud images. Esses images de sistema ope­ra­ci­o­nal pré-con­fi­gu­ra­dos, ge­ral­mente Ubuntu ou Debian, são oti­mi­za­dos para a ini­ci­a­li­za­ção au­to­má­tica com cloud-init. Neste exemplo, usamos um cloud image do Ubuntu 22.04 LTS, pois ele é estável, bem do­cu­men­tado e ideal para uso com Ku­ber­ne­tes.

Primeiro, faça o download do cloud image atual do Ubuntu di­re­ta­mente para o seu host Proxmox. Para isso, conecte-se ao seu servidor Proxmox via SSH e mude para o diretório em que o Proxmox armazena arquivos ISO e de imagem:

cd /var/lib/vz/template/iso

Em seguida, faça o download do image do Ubuntu com o seguinte comando:

wget -O ubuntu-22.04-server-cloudimg-amd64.img https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

scp ubuntu-22.04-server-cloudimg-amd64.img root@<proxmox-ip>:/var/lib/vz/template/iso/

Assim que o image estiver no host Proxmox, você poderá criar a partir dele uma nova máquina virtual que, mais tarde, servirá como template. Para isso, primeiro crie uma VM vazia com um ID exclusivo, por exemplo 9000, e atribua a ela recursos básicos de hardware:

qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

Agora, importe o Cloud Image baixado an­te­ri­or­mente como disco rígido virtual no ar­ma­ze­na­mento desejado (no nosso exemplo, local-lvm):

qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm

Em seguida, você pode conectar o disco importado à VM e con­fi­gu­rar o con­tro­la­dor correto. Dessa forma, o image é vinculado ao con­tro­la­dor SCSI virtual da máquina virtual:

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0

Para que, mais tarde, ao clonar as VMs, você possa definir au­to­ma­ti­ca­mente endereços IP, nomes de host e chaves SSH, é ne­ces­sá­rio um drive Cloud-Init. Esse drive virtual contém os dados de con­fi­gu­ra­ção aplicados au­to­ma­ti­ca­mente na ini­ci­a­li­za­ção da VM. Adicione o drive Cloud-Init e defina a ordem de boot com os seguintes comandos:

qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0

Ative também o QEMU Guest Agent para que o Proxmox possa ler in­for­ma­ções de status da VM pos­te­ri­or­mente e configure um console serial para ter acesso direto ao console da VM em caso de emer­gên­cia:

qm set 9000 --agent 1
qm set 9000 --serial0 socket --vga serial0

Se tudo estiver con­fi­gu­rado cor­re­ta­mente, você poderá trans­for­mar sua máquina virtual em um chamado template. No Proxmox, templates servem como modelo, a partir do qual você poderá criar quantos clones quiser pos­te­ri­or­mente. Assim, eles são perfeitos para seus nós de Ku­ber­ne­tes.

qm template 9000

Após esta etapa, o template do Ubuntu estará pronto e servirá como base para seus nós master e worker do Ku­ber­ne­tes.

Etapa 3: clonar VMs para master/worker via CLI

Em uma terceira etapa, você cria, a partir do template criado an­te­ri­or­mente, as máquinas virtuais que mais tarde servirão como nós master e worker do seu cluster Ku­ber­ne­tes. Cada uma dessas VMs recebe seu próprio endereço IP, um hostname exclusivo e uma chave SSH para acesso seguro. O Proxmox realiza a con­fi­gu­ra­ção básica au­to­ma­ti­ca­mente via cloud-init, para que você não precise mais fazer nenhuma con­fi­gu­ra­ção manual dentro das máquinas virtuais.

Primeiro, clone o template criado an­te­ri­or­mente (neste exemplo, com o ID 9000) e, a partir dele, crie três máquinas virtuais: uma para o nó master e duas para os res­pec­ti­vos nós worker. Nesse processo, você pode ajustar CPU e memória RAM in­di­vi­du­al­mente:

qm clone 9000 101 --name k8s-master-1 --full true
qm set 101 --cores 2 --memory 4096
qm clone 9000 102 --name k8s-worker-1 --full true
qm set 102 --cores 2 --memory 4096
qm clone 9000 103 --name k8s-worker-2 --full true
qm set 103 --cores 2 --memory 4096

Em seguida, você define via cloud-init as con­fi­gu­ra­ções básicas de rede, o hostname e a chave SSH. Nesse processo, é possível atribuir endereços IP fixos ou usar DHCP. Neste exemplo, são uti­li­za­dos endereços estáticos:

# Configurar master
qm set 101 --ipconfig0 ip=192.168.1.10/24,gw=192.168.1.1
qm set 101 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 101 --ciuser ubuntu
qm set 101 --nameserver 192.168.1.1
qm set 101 --description "K8s Master 1"
# Configurar worker
qm set 102 --ipconfig0 ip=192.168.1.11/24,gw=192.168.1.1
qm set 102 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 102 --ciuser ubuntu
qm set 103 --ipconfig0 ip=192.168.1.12/24,gw=192.168.1.1
qm set 103 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 103 --ciuser ubuntu

Por fim, inicie as três máquinas com os comandos de terminal abaixo:

qm start 101
qm start 102
qm start 103

Aguarde um momento até que os sistemas estejam to­tal­mente ini­ci­a­li­za­dos e depois teste a conexão via SSH. Se tudo estiver fun­ci­o­nando, você pode, por exemplo, fazer login no nó master com o seguinte comando:

ssh ubuntu@192.168.1.10

Etapa 4: adicionar a con­fi­gu­ra­ção básica em todas as máquinas virtuais

Antes de instalar o Ku­ber­ne­tes nas VMs, você deve fazer algumas con­fi­gu­ra­ções em todo o sistema, ne­ces­sá­rias para uma operação estável. Isso inclui desativar o swap, ajustar pa­râ­me­tros do kernel para rede e en­ca­mi­nha­mento de IP, além de sin­cro­ni­zar a hora do sistema. Essas medidas garantem que o Ku­ber­ne­tes funcione cor­re­ta­mente e que as funções de rede dentro dos con­têi­ne­res operem de forma confiável.

Primeiro, desative o swap em todos os nós, pois o Ku­ber­ne­tes exige isso para a lógica do scheduler. Além disso, remova a entrada cor­res­pon­dente em /etc/fstab, para que o swap não seja ativado novamente após uma rei­ni­ci­a­li­za­ção:

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

Em seguida, configure os pa­râ­me­tros do kernel para garantir que os pacotes de rede entre con­têi­ne­res e nós possam ser pro­ces­sa­dos cor­re­ta­mente:

cat <<'EOF' | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
# Aplicar alterações
sudo sysctl --system

Outro passo im­por­tante é sin­cro­ni­zar a hora do sistema, para que cer­ti­fi­ca­dos e com­po­nen­tes do cluster não apre­sen­tem problemas devido a di­fe­ren­ças de horário. Para isso, você pode instalar e iniciar o chrony:

sudo apt update && sudo apt install -y chrony
sudo systemctl enable --now chrony

Por fim, recomenda-se instalar alguns uti­li­tá­rios básicos, que serão úteis nas etapas pos­te­ri­o­res:

sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Após essas etapas, todos os nós estão pre­pa­ra­dos de forma pa­dro­ni­zada, a swap está de­sa­ti­vada, as con­fi­gu­ra­ções de rede foram definidas cor­re­ta­mente e a hora está sin­cro­ni­zada. Suas VMs agora estão prontas para a ins­ta­la­ção do Ku­ber­ne­tes e para a con­fi­gu­ra­ção do seu cluster.

Etapa 5: escolha da dis­tri­bui­ção do Ku­ber­ne­tes

Antes de iniciar a ins­ta­la­ção pro­pri­a­mente dita do Ku­ber­ne­tes, você deve escolher uma dis­tri­bui­ção adequada. Com base nos seus re­qui­si­tos, é possível optar entre duas opções re­co­men­da­das:

• RKE2 (Rancher Ku­ber­ne­tes Engine 2): o RKE2 é uma dis­tri­bui­ção do Ku­ber­ne­tes estável e pronta para produção, de­sen­vol­vida pela Rancher. Ela é es­pe­ci­al­mente indicada se você quiser usar mais tarde uma ad­mi­nis­tra­ção gráfica via Rancher ou planejar um cluster com vários nós de control plane.
• k3s: k3s é uma dis­tri­bui­ção do Ku­ber­ne­tes enxuta, ideal para ambientes de teste, home labs ou sistemas com recursos limitados. Ela é muito fácil de instalar e requer menos memória e CPU. Para a criação de um cluster Ku­ber­ne­tes robusto no Proxmox, que também possa ser operado em um cenário próximo ao de produção, recomenda-se o RKE2. No entanto, se você quiser con­fi­gu­rar ra­pi­da­mente um pequeno cluster de teste ou de de­sen­vol­vi­mento, o k3s é a al­ter­na­tiva mais prática. No restante deste guia, será utilizado o RKE2.

Etapa 6: instalar o RKE2 no nó master

Após a con­fi­gu­ra­ção básica das suas máquinas virtuais ser concluída, você pode iniciar a ins­ta­la­ção do RKE2 no nó master. Para isso, faça login via SSH no nó master:

ssh ubuntu@192.168.1.10

Agora, baixe o script de ins­ta­la­ção do RKE2 e execute-o. Op­ci­o­nal­mente, você pode informar um canal com a versão desejada:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash -

Após a ins­ta­la­ção, habilite o serviço do servidor RKE2 e inicie-o ime­di­a­ta­mente:

sudo systemctl enable --now rke2-server.service

Verifique com o comando a seguir se o servidor RKE2 está fun­ci­o­nando cor­re­ta­mente:

sudo systemctl status rke2-server

Para poder gerenciar o cluster Ku­ber­ne­tes a partir do seu com­pu­ta­dor local, copie o arquivo kubeconfig:

sudo chmod 644 /etc/rancher/rke2/rke2.yaml
scp ubuntu@192.168.1.10:/etc/rancher/rke2/rke2.yaml ~/rke2-kubeconfig

Em seguida, ajuste o IP do master no arquivo para que o kubectl acesse o servidor cor­re­ta­mente:

sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig
export KUBECONFIG=~/rke2-kubeconfig

Com este comando, você pode verificar se o nó master está acessível:

kubectl get nodes

Se o master for exibido, a ins­ta­la­ção foi concluída com sucesso e, no próximo passo, você poderá adicionar os nós de worker.

Etapa 7: instalar o RKE2 Agent nos nós de worker

Depois que o nó master for con­fi­gu­rado com sucesso, você poderá integrar os nós de worker ao seu cluster. Para isso, instale em cada worker o RKE2 Agent e conecte-o ao master.

No nó master, primeiro você precisa do Node Token, que é ne­ces­sá­rio para a au­ten­ti­ca­ção dos workers no cluster:

sudo cat /var/lib/rancher/rke2/server/node-token

Anote o token. Você vai precisar desse valor já nos nós de worker.

Acesse via SSH cada nó de worker:

ssh ubuntu@192.168.1.11

Baixe o script de ins­ta­la­ção do RKE2 e instale o agente com o seguinte comando:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh -

Em seguida, crie o arquivo de con­fi­gu­ra­ção do agente e informe nele o IP do master e o token do nó:

sudo mkdir -p /etc/rancher/rke2
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://192.168.1.10
token: <TOKEN_HIER_EINFÜGEN>
EOF

Por fim, ative e inicie o serviço do agente RKE2:

sudo systemctl enable --now rke2-agent.service

Repita esse processo para todos os nós worker do cluster. Após alguns minutos, você pode verificar no master se os nós worker estão co­nec­ta­dos cor­re­ta­mente:

kubectl get nodes

Agora você deve ver todos os nós: o master e os workers adi­ci­o­na­dos re­cen­te­mente. Com isso, seu cluster está completo e pronto para a ins­ta­la­ção de plugins de rede, load balancer e outros com­po­nen­tes do Ku­ber­ne­tes.

Etapa 8: instalar CNI de rede e Lo­ad­Ba­lan­cer

Depois que os nós master e worker forem con­fi­gu­ra­dos com sucesso, você precisará de um Container Network Interface (CNI) para que os pods no cluster possam se comunicar entre si, além de um Load Balancer para tornar os serviços aces­sí­veis na rede. Neste guia, usamos o Calico como CNI e o MetalLB para a fun­ci­o­na­li­dade de load balancing em camada 2.

O Calico es­ta­be­lece as conexões de rede entre os pods, controla a atri­bui­ção de IPs e permite, op­ci­o­nal­mente, políticas de rede. Você pode instalá-lo com um comando simples no terminal.

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

Em seguida, verifique se todos os pods do Calico foram iniciados com sucesso:

kubectl get pods -n kube-system

Todos os pods devem exibir o status Running ou Completed. Se alguns pods ainda estiverem com Pending, aguarde alguns minutos, pois o Calico leva um tempo para dis­tri­buir a con­fi­gu­ra­ção de rede em todos os nós.

O Ku­ber­ne­tes oferece suporte, por padrão, ao tipo de Service Lo­ad­Ba­lan­cer, que exige IPs externos. Em um cluster auto-hospedado, como no Proxmox, utiliza-se o MetalLB para isso. Primeiro, instale o MetalLB:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

Em seguida, crie um pool de IPs a partir do qual o MetalLB pode atribuir endereços IP aos Services. Ajuste o intervalo de IPs de acordo com sua rede local:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: my-ip-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2adv
namespace: metallb-system
spec: {}
EOF

Verifique também aqui se os pods do MetalLB estão sendo exe­cu­ta­dos cor­re­ta­mente:

kubectl get pods -n metallb-system

Assim que todos os pods estiverem com o status Running, sua rede estará con­fi­gu­rada. Agora você pode usar Services do Ku­ber­ne­tes do tipo Lo­ad­Ba­lan­cer para tornar apli­ca­ti­vos aces­sí­veis na LAN. Com isso, seu cluster Ku­ber­ne­tes no Proxmox estará to­tal­mente con­fi­gu­rado e pronto para fazer deploy de apli­ca­ções e gerenciar recursos de rede.