Skip to main content

Como criar um volume para um app

Este guia explica como provisionar um PersistentVolumeClaim (PVC) no cluster e referenciá-lo em um app via GitOps.

Toda a gestão de storage é feita no repositório homelab. O ArgoCD detecta automaticamente novos PVCs e os provisiona sem intervenção manual.

Pré-requisitos​

  • Acesso de escrita ao repositório homelab
  • Acesso de escrita ao repositório kelbi-applications (para associar o volume a um app)

Passo 1 — Criar o PVC no homelab​

Crie um diretório em homelab/storage/ com o nome do PVC e um arquivo values.yaml:

homelab/
└── storage/
    └── meu-pvc/
        └── values.yaml

homelab/storage/meu-pvc/values.yaml:

name: meu-pvc
namespace: apps
size: 5Gi
storageClass: local-path
accessMode: ReadWriteOnce
description: "Descrição do que esse volume armazena e qual app o usa"
CampoObrigatórioDescrição
nameSimNome do PVC no Kubernetes
namespaceNãoPadrão: apps
sizeSimTamanho do volume (ex: 5Gi, 20Gi)
storageClassNãoPadrão: local-path (k3s)
accessModeNãoPadrão: ReadWriteOnce
descriptionNãoDocumentação — quem usa esse volume
Nomeação

Use nomes descritivos que identifiquem o app e o conteúdo. Exemplos: halk-en-patch-data, kelbi-static-assets.

Passo 2 — Abrir PR e fazer merge​

Depois do merge na branch principal do homelab, o ApplicationSet cluster-storage detecta o novo values.yaml automaticamente e cria uma Application no ArgoCD.

O ArgoCD então aplica o PVC no cluster via o chart kelbi-storage. O local-path-provisioner do k3s provisiona o volume imediatamente.

Para verificar:

kubectl get pvc -n apps meu-pvc
# NAME       STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS   AGE
# meu-pvc    Bound    pvc-...     5Gi        RWO            local-path     1m
WaitForFirstConsumer

Se o PVC ficar em Pending com a mensagem waiting for first consumer to be created before binding, é comportamento esperado. A StorageClass local-path-immediate usa volumeBindingMode: WaitForFirstConsumer — o volume só é provisionado quando o primeiro pod montar o PVC.

Isso significa que o PVC vai vincular automaticamente quando o app for deployado no Passo 3. Não é necessária nenhuma ação manual.

Para verificar o motivo do Pending:

kubectl describe pvc -n apps meu-pvc

Criar Volume

PVC protegido contra deleção

O chart aplica helm.sh/resource-policy: keep e o ApplicationSet usa prune: false. O PVC nunca é deletado automaticamente — nem por helm delete, nem por sync do ArgoCD. Para deletar, é necessário executar kubectl delete pvc manualmente.

Passo 3 — Referenciar o PVC no app​

No repositório kelbi-applications, adicione o bloco storage no values.yaml do app:

# kelbi-applications/apps/<org>/<app>/values.yaml
storage:
  - name: meu-volume        # nome lógico interno ao pod
    claim: meu-pvc          # nome do PVC criado no passo 1
    mountPath: /app/data
    readOnly: false

O chart kelbi-app gera automaticamente o volume e o volumeMount no Deployment.

note

O bloco storage faz parte da RFC 0001 — Storage. O campo volumes/volumeMounts raw continua funcionando enquanto a migração não é concluída.

Exemplo completo​

Cenário: novo volume para meu-api​

1. homelab``/storage/meu-api-data/values.yaml

name: meu-api-data
size: 10Gi
description: "Dados persistentes do meu-api — uploads de usuários"

2. kelbi-applications/apps/Invasor-de-Fronteiras/meu-api/values.yaml

app:
  name: meu-api
  image: ghcr.io/invasor-de-fronteiras/meu-api:latest
  port: 3000

storage:
  - name: data
    claim: meu-api-data
    mountPath: /app/data

Fluxo resumido​