Armazenamento persistente no Kubernetes: local-path ou Longhorn no k3s

Como guardar dados no Kubernetes sem perdê-los: PVC com local-path do k3s ou Longhorn replicado, com prós, contras e passo a passo.

Para que serve

Containers são descartáveis: tudo o que é gravado dentro deles some quando o pod é recriado. Bancos de dados, uploads e filas precisam de armazenamento persistente no Kubernetes, feito com PersistentVolumeClaims (PVC). Este artigo compara as duas opções mais usadas em k3s num servidor dedicado: o local-path, que já vem instalado, e o Longhorn, que replica os volumes entre nós.

Pré-requisitos

• Cluster k3s funcionando (veja Como instalar o k3s em servidor dedicado) e Helm instalado (veja Helm na prática).
• Para o Longhorn: preferencialmente três nós, cada um com um disco virtual dedicado (ex.: 100 GB) e sistema de arquivos ext4 ou XFS.

Comparação rápida

Opção 1: usar o local-path

1. Confira o StorageClass padrão:

   kubectl get storageclass

   Deve aparecer local-path (default).
2. Crie um PVC e um pod de teste (pvc-teste.yaml):

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: dados
   spec:
     accessModes: [ReadWriteOnce]
     storageClassName: local-path
     resources:
       requests:
         storage: 5Gi
   ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: teste-volume
   spec:
     containers:
       - name: app
         image: busybox:1.37
         command: ["sh", "-c", "date >> /dados/log.txt; sleep 3600"]
         volumeMounts:
           - name: dados
             mountPath: /dados
     volumes:
       - name: dados
         persistentVolumeClaim:
           claimName: dados

   Aplique com kubectl apply -f pvc-teste.yaml. O volume só é criado quando o pod é agendado (modo WaitForFirstConsumer).
3. Mude o local de gravação, se quiser. Para usar um disco específico (ex.: um NVMe montado em /srv/k8s), inicie o k3s com default-local-storage-path: /srv/k8s no /etc/rancher/k3s/config.yaml. Faça isso antes de criar volumes.
4. Pensando em backup com Velero: por padrão o local-path cria volumes do tipo hostPath, que o backup de sistema de arquivos do Velero ignora. Para volumes novos, adicione a anotação volumeType: local no PVC. Detalhes no artigo Backup de Kubernetes com etcd snapshot e Velero.

Opção 2: instalar o Longhorn

1. Prepare todos os nós (Debian/Ubuntu):

   apt update
   apt install -y open-iscsi nfs-common cryptsetup dmsetup
   systemctl enable --now iscsid

2. Monte o disco dedicado em cada nó. Adicione um disco à VM no Proxmox, formate e monte em /var/lib/longhorn:

   mkfs.ext4 /dev/sdb
   mkdir -p /var/lib/longhorn
   echo '/dev/sdb /var/lib/longhorn ext4 defaults 0 2' >> /etc/fstab
   mount -a

   Confira o nome do disco com lsblk antes de formatar.
3. Valide os requisitos com a ferramenta oficial longhornctl (baixe a versão igual à do Longhorn na página de releases do projeto) e rode longhornctl check preflight. Corrija o que ela apontar.
4. Instale pelo Helm sem torná-lo o StorageClass padrão (o k3s recria o local-path como padrão a cada reinício, e dois padrões causam confusão):

   helm repo add longhorn https://charts.longhorn.io
   helm repo update
   helm install longhorn longhorn/longhorn \
     --namespace longhorn-system --create-namespace \
     --version 1.13.0 \
     --set persistence.defaultClass=false \
     --set persistence.defaultClassReplicaCount=3
   
   kubectl -n longhorn-system get pods

   Com apenas dois nós, use defaultClassReplicaCount=2. Confira na documentação a versão atual e a versão mínima de Kubernetes exigida.
5. Use o Longhorn nos PVCs com storageClassName: longhorn. Volumes do Longhorn são ReadWriteOnce; ele também oferece ReadWriteMany via NFS interno, útil para pastas compartilhadas.
6. Acesse a interface web com segurança. Ela não tem login; não a publique em Ingress sem autenticação. Use um túnel temporário:

   kubectl -n longhorn-system port-forward svc/longhorn-frontend 8080:80

   e abra http://localhost:8080. Lá você configura o backup target (um bucket S3) e agenda snapshots e backups recorrentes.

Como saber se funcionou

kubectl get pvc,pv
kubectl exec teste-volume -- cat /dados/log.txt
kubectl delete pod teste-volume && kubectl apply -f pvc-teste.yaml
kubectl exec teste-volume -- cat /dados/log.txt

O PVC deve estar Bound e, depois de recriar o pod, o arquivo deve ter duas linhas: os dados sobreviveram. No Longhorn, a interface deve mostrar o volume como Healthy, com todas as réplicas.

Problemas comuns

PVC fica em Pending

Com local-path é normal até um pod usar o PVC. Se persistir, veja kubectl describe pvc dados: nome de StorageClass errado ou falta de espaço são as causas mais comuns.

Pod não sobe: "volume node affinity conflict"

Volume local-path fica preso ao nó onde foi criado. Se o nó saiu do cluster, os dados estão no disco dele; restaure de backup ou devolva o nó.

Longhorn com volume Degraded

Uma réplica está faltando ou reconstruindo, geralmente porque um nó reiniciou ou o disco encheu. O Longhorn reconstrói sozinho quando o nó volta; mantenha pelo menos 25% de espaço livre nos discos dos nós.

Pods do Longhorn em CrashLoop com erro de iSCSI

Falta o open-iscsi ou o iscsid não está ativo em algum nó. Rode o passo 1 em todos os nós.

Perguntas frequentes

Posso usar NFS em vez de Longhorn?

Sim, com o provisionador csi-driver-nfs apontando para um servidor NFS (por exemplo, uma VM dedicada). É simples, mas bancos de dados costumam ter desempenho ruim e problemas de lock sobre NFS.

E o Ceph do Proxmox?

O Ceph faz sentido com três ou mais servidores físicos. Em um único servidor ele adiciona complexidade sem ganho de redundância.

Banco de dados deve ficar no Kubernetes?

Pode, com operadores maduros (CloudNativePG, por exemplo) e armazenamento local rápido. Muitas equipes preferem manter o banco em uma VM separada e só as aplicações no cluster.

Leitura complementar

• Armazenamento no k3s
• Requisitos e instalação do Longhorn
• Persistent Volumes (documentação do Kubernetes)

Precisa de ajuda?

Se um NVMe apresentar erros ou o espaço do servidor não bater com o esperado, abra um ticket com a saída de lsblk e smartctl -a do disco.