# Criar cluster Kubernetes no Proxmox: guia passo a passo

A criação de um cluster Kubernetes no Proxmox permite operar, em um ambiente virtualizado e auto-hospedado, uma **plataforma de orquestração de contêineres de alto desempenho**. Isso é ideal para ambientes de teste, fluxos de trabalho de desenvolvimento e CI, ou também para cenários menores de produção. Neste guia, você vai aprender passo a passo como configurar máquinas virtuais no Proxmox e, a partir delas, montar um cluster Kubernetes estável.

## Passo 1: verificar os pré-requisitos

Antes de iniciar a configuração do cluster Kubernetes, você deve garantir que seu ambiente atenda a todos os pré-requisitos técnicos. Uma base bem-preparada economiza muito tempo depois e evita erros de configuração.

Você precisa, primeiro, de uma instalação funcional do [Proxmox](https://www.ionos.com/pt-br/digitalguide/servidor/conhecimento/proxmox/) VE. Por motivos de desempenho, recomenda-se uma [instalação bare-metal do Proxmox](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/proxmox-bare-metal-instalacao/). Tanto o **acesso via web** pela interface do Proxmox quanto o **acesso via SSH** à linha de comando devem estar disponíveis. Via [SSH](https://www.ionos.com/pt-br/digitalguide/servidor/ferramentas/o-que-e-ssh-protocolo-ssh/), você pode executar comandos, fazer upload de imagens e automatizar configurações.

Para um cluster Kubernetes estável, você também precisa de várias máquinas virtuais. Recomenda-se os seguintes [nós do Kubernetes](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/kubernetes-nodes/):

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

Assim, você obtém um certo nível de redundância e pode operar o [Kubernetes](https://www.ionos.com/pt-br/digitalguide/servidor/conhecimento/o-que-e-kubernetes/) da forma como é previsto em ambientes de produção reais. Para fins de teste, porém, uma configuração menor com um nó mestre e um nó worker também é suficiente.

Seu host Proxmox também deve ter uma **interface de bridge funcional**, que permita às máquinas virtuais o acesso à rede local e, se necessário, à internet. Isso é importante para que as VMs possam baixar atualizações e instalar componentes do Kubernetes posteriormente.

Dica Para ambientes de produção, também é recomendável configurar backups regulares das máquinas virtuais por meio de um [Proxmox Backup Server](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/proxmox-backup-server/). Assim, você pode restaurar rapidamente seus nós do Kubernetes quando necessário e minimizar o tempo de indisponibilidade.

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

Instalações do Kubernetes podem ser feitas com mais facilidade usando os **chamados cloud images**. Esses images de sistema operacional pré-configurados, geralmente Ubuntu ou Debian, são otimizados para a inicialização automática com `cloud-init`. Neste exemplo, usamos um cloud image do Ubuntu 22.04 LTS, pois ele é estável, bem documentado e ideal para uso com Kubernetes.

Primeiro, faça o download do cloud image atual do Ubuntu diretamente 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:

```bash
cd /var/lib/vz/template/iso
```

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

```bash
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
```

Nota Como alternativa, você também pode baixar o image primeiro para o seu computador local e depois transferi-lo para o host Proxmox via `scp` (Secure Copy):

```bash
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:

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

Agora, importe o Cloud Image baixado anteriormente **como disco rígido virtual no armazenamento desejado** (no nosso exemplo, `local-lvm`):

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

Dica Se o seu cluster Proxmox tiver um armazenamento distribuído, você também pode, alternativamente, salvar o image no storage Ceph. A integração de [Ceph no Proxmox](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/ceph-no-proxmox/) oferece uma solução de armazenamento altamente disponível e escalável para suas VMs de Kubernetes.

Em seguida, você pode conectar o disco importado à VM e configurar o controlador correto. Dessa forma, o image é vinculado ao controlador SCSI virtual da máquina virtual:

```bash
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 automaticamente endereços IP, nomes de host e chaves SSH, é necessário um drive Cloud-Init. Esse drive virtual contém os dados de configuração aplicados automaticamente na inicialização da VM. Adicione o drive Cloud-Init e defina a ordem de boot com os seguintes comandos:

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

Ative também o [QEMU](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/qemu/) Guest Agent para que o Proxmox possa **ler informações de status da VM** posteriormente e configure um console serial para ter acesso direto ao console da VM em caso de emergência:

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

Se tudo estiver configurado corretamente, você poderá transformar sua máquina virtual em um chamado template. **No Proxmox, templates servem como modelo**, a partir do qual você poderá criar quantos clones quiser posteriormente. Assim, eles são perfeitos para seus nós de Kubernetes.

```bash
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 Kubernetes.

## Etapa 3: clonar VMs para master/worker via CLI

Em uma terceira etapa, você cria, a partir do template criado anteriormente, as máquinas virtuais que mais tarde servirão como **nós master e worker do seu cluster Kubernetes**. 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 configuração básica automaticamente via `cloud-init`, para que você não precise mais fazer nenhuma configuração manual dentro das máquinas virtuais.

Primeiro, clone o template criado anteriormente (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 respectivos nós worker. Nesse processo, você pode ajustar CPU e memória RAM individualmente:

```bash
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 configuraçõ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 utilizados endereços estáticos:

```bash
# 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
```

Nota Adapte os endereços IP de exemplo usados aqui à sua própria rede. Use valores dentro da faixa de IP do seu roteador e garanta que cada VM receba um endereço exclusivo que ainda não esteja em uso.

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

```bash
qm start 101
qm start 102
qm start 103
```

Aguarde um momento até que os sistemas estejam totalmente inicializados e **depois teste a conexão via SSH**. Se tudo estiver funcionando, você pode, por exemplo, fazer login no nó master com o seguinte comando:

```none
ssh ubuntu@192.168.1.10
```

## Etapa 4: adicionar a configuração básica em todas as máquinas virtuais

Antes de instalar o Kubernetes nas VMs, você deve fazer algumas configurações em todo o sistema, necessárias para uma operação estável. Isso inclui desativar o swap, ajustar parâmetros do kernel para rede e encaminhamento de IP, além de sincronizar a hora do sistema. Essas medidas garantem que o Kubernetes funcione corretamente e que as funções de rede dentro dos contêineres operem de forma confiável.

Primeiro, desative o swap em todos os nós, pois o Kubernetes **exige isso para a lógica do scheduler**. Além disso, remova a entrada correspondente em `/etc/fstab`, para que o swap não seja ativado novamente após uma reinicialização:

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

Em seguida, configure os parâmetros do kernel para garantir que os pacotes de rede entre contêineres e nós possam ser processados corretamente:

```bash
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 importante é sincronizar a hora do sistema, para que certificados e componentes do cluster não apresentem problemas devido a diferenças de horário. Para isso, você pode instalar e iniciar o `chrony`:

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

Por fim, recomenda-se instalar alguns **utilitários básicos**, que serão úteis nas etapas posteriores:

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

Após essas etapas, todos os nós estão preparados de forma padronizada, a swap está desativada, as configurações de rede foram definidas corretamente e a hora está sincronizada. Suas VMs agora estão prontas para a instalação do Kubernetes e para a configuração do seu cluster.

## Etapa 5: escolha da distribuição do Kubernetes

Antes de iniciar a instalação propriamente dita do Kubernetes, você deve escolher uma **distribuição adequada**. Com base nos seus requisitos, é possível optar entre duas opções recomendadas:

- **RKE2 (Rancher Kubernetes Engine 2)**: o RKE2 é uma distribuição do Kubernetes estável e pronta para produção, desenvolvida pela Rancher. Ela é especialmente indicada se você quiser usar mais tarde uma administração gráfica via Rancher ou planejar um cluster com vários nós de control plane.
- **k3s**: [k3s](https://www.ionos.com/pt-br/digitalguide/servidor/conhecimento/o-que-e-k3s/) é uma distribuição do Kubernetes 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 Kubernetes 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 configurar rapidamente um pequeno cluster de teste ou de desenvolvimento, o k3s é a alternativa mais prática. No restante deste guia, será utilizado o RKE2.

## Etapa 6: instalar o RKE2 no nó master

Após a configuração básica das suas máquinas virtuais ser concluída, você pode iniciar a **instalação do RKE2 no nó master**. Para isso, faça login via SSH no nó master:

```bash
ssh ubuntu@192.168.1.10
```

Agora, baixe o script de instalação do RKE2 e execute-o. Opcionalmente, você pode informar um canal com a versão desejada:

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

Após a instalação, habilite o serviço do servidor RKE2 e inicie-o imediatamente:

```bash
sudo systemctl enable --now rke2-server.service
```

Verifique com o comando a seguir se o servidor RKE2 está funcionando corretamente:

```bash
sudo systemctl status rke2-server
```

Para poder gerenciar o cluster Kubernetes a partir do seu computador local, copie o arquivo `kubeconfig`:

```bash
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 corretamente:

```bash
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:

```bash
kubectl get nodes
```

Se o master for exibido, a instalaçã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 configurado 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 é necessário para a autenticação dos workers no cluster:

```bash
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:

```bash
ssh ubuntu@192.168.1.11
```

Baixe o script de instalação do RKE2 e instale o agente com o seguinte comando:

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

Em seguida, crie o arquivo de configuração do agente e informe nele o IP do master e o token do nó:

```bash
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:

```bash
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 conectados corretamente:

```bash
kubectl get nodes
```

Agora você deve ver todos os nós: o master e os workers adicionados recentemente. Com isso, seu cluster está completo e pronto para a instalação de plugins de rede, load balancer e outros componentes do Kubernetes.

## Etapa 8: instalar CNI de rede e LoadBalancer

Depois que os nós master e worker forem configurados 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 acessíveis na rede. Neste guia, usamos o Calico como CNI e o MetalLB para a funcionalidade de [load balancing](https://www.ionos.com/pt-br/digitalguide/servidor/conhecimento/melhorar-tempos-de-acesso-ao-servidor-com-load-balancers/) em camada 2.

**O Calico estabelece as conexões de rede entre os pods**, controla a atribuição de IPs e permite, opcionalmente, políticas de rede. Você pode instalá-lo com um comando simples no terminal.

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

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

```bash
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 distribuir a configuração de rede em todos os nós.

O Kubernetes oferece suporte, por padrão, ao **tipo de Service LoadBalancer**, que exige IPs externos. Em um cluster auto-hospedado, como no Proxmox, utiliza-se o MetalLB para isso. Primeiro, instale o MetalLB:

```bash
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:

```bash
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 executados corretamente:

```bash
kubectl get pods -n metallb-system
```

Assim que todos os pods estiverem com o status `Running`, sua rede estará configurada. Agora você pode usar Services do Kubernetes do tipo LoadBalancer para tornar aplicativos acessíveis na LAN. Com isso, seu cluster Kubernetes no Proxmox estará totalmente configurado e pronto para fazer deploy de aplicações e gerenciar recursos de rede.


This is a markdown version of: [https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/cluster-kubernetes-no-proxmox/](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/cluster-kubernetes-no-proxmox/) for AI/LLM consumption.