Skip to main content

Mover arquivos para um PVC

Procedimento para migrar dados de um volume hostPath existente para um PersistentVolumeClaim gerenciado pelo homelab.

Faz parte da Fase 2 da RFC 0001 — Storage.

Pré-requisitos​

  • PVC já criado e visível no cluster (kubectl get pvc -n apps)
  • Acesso ao nó via SSH (para verificar paths se necessário)
  • App com downtime tolerado durante a janela de migração (ou migração a quente se o app suportar)

Procedimento​

1. Confirmar que o PVC existe​

kubectl get pvc -n apps <nome-do-pvc>

Status esperado: Pending (normal — WaitForFirstConsumer até o primeiro pod montar).

2. Criar pod de migração​

O pod monta simultaneamente o hostPath de origem e o PVC de destino. Isso dispara o provisionamento do PVC e permite a cópia dentro do próprio cluster.

Salvar o manifesto em um arquivo temporário (substituindo os placeholders):

migration.yaml
apiVersion: v1
kind: Pod
metadata:
  name: migrate-<nome-do-pvc>
  namespace: apps
spec:
  restartPolicy: Never
  containers:
    - name: migrate
      image: alpine
      command: ["sleep", "infinity"]
      volumeMounts:
        - name: source
          mountPath: /source
        - name: dest
          mountPath: /dest
  volumes:
    - name: source
      hostPath:
        path: /root/kelbi-volumes/<path-de-origem>
        type: Directory
    - name: dest
      persistentVolumeClaim:
        claimName: <nome-do-pvc>
kubectl apply -f migration.yaml

Aguardar o pod ficar Running:

kubectl wait pod -n apps migrate-<nome-do-pvc> --for=condition=Ready --timeout=60s

O PVC deve ter mudado para Bound:

kubectl get pvc -n apps <nome-do-pvc>

3. Copiar os dados​

kubectl exec -n apps migrate-<nome-do-pvc> -- sh -c "cp -av /source/. /dest/"

4. Verificar a cópia​

Confirmar que os arquivos chegaram e que o tamanho bate:

# contagem de arquivos na origem
kubectl exec -n apps migrate-<nome-do-pvc> -- find /source -type f | wc -l

# contagem de arquivos no destino
kubectl exec -n apps migrate-<nome-do-pvc> -- find /dest -type f | wc -l

# uso de disco comparado
kubectl exec -n apps migrate-<nome-do-pvc> -- du -sh /source /dest

5. Remover o pod de migração​

kubectl delete pod -n apps migrate-<nome-do-pvc>

6. Atualizar o app em kelbi-applications​

Substituir o volume hostPath raw pelo bloco storage[]:

# antes
advanced:
  volumes:
    - name: data
      hostPath:
        path: /root/kelbi-volumes/<path-de-origem>
        type: Directory
  volumeMounts:
    - name: data
      mountPath: /app/data

# depois
storage:
  - name: data
    claim: <nome-do-pvc>
    mountPath: /app/data

Fazer merge e aguardar o ArgoCD sincronizar.

7. Verificar o app​

# confirmar que o pod subiu com o PVC
kubectl get pod -n apps -l app=<nome-do-app>
kubectl describe pod -n apps <nome-do-pod> | grep -A5 "Volumes:"

# confirmar que o PVC está bound e em uso
kubectl get pvc -n apps <nome-do-pvc>

Referência rápida — volumes a migrar​

PVChostPath de origemApps
halk-en-patch-data/root/kelbi-volumes/halk-patch-server/enhalk-en-api, halk-en-cdn
halk-jp-patch-data/root/kelbi-volumes/halk-patch-server/jphalk-jp-api, halk-jp-cdn
kelbi-static-assets/root/kelbi-volumes/kelbi/statickelbi-api, kelbi-cdn, kelbi-jobs
Múltiplos apps no mesmo PVC

Quando mais de um app usa o mesmo PVC (ex: halk-en-api e halk-en-cdn), migrar todos ao mesmo tempo na mesma janela de manutenção para evitar inconsistência entre o app que escreve (hostPath) e o que lê (PVC).

Rollback​

Se algo der errado após o Passo 6, reverter o values.yaml do app para o hostPath original e fazer merge. O ArgoCD vai re-deployar com o volume antigo. Os dados no hostPath continuam intactos — o pod de migração não remove a origem.