Arregla tu PVC Pendiente en Kubernetes

Un PersistentVolumeClaim (PVC) en Kubernetes queda stuck en pending cuando no encuentra un volumen disponible para vincularse. Las causas más comunes son: StorageClass inexistente, provisioner caído, modo de vinculación incorrecto o restricciones de acceso incompatibles. Diagnosticarlo es simple con kubectl describe pvc, pero resolverlo requiere entender cómo funciona realmente la vinculación de volúmenes en Kubernetes.

En 30 segundos

Un PVC pending espera vincular con un PersistentVolume (PV) pero no encuentra uno compatible
Verificá que la StorageClass exista: kubectl get storageclass
Entendé la diferencia entre Immediate (vincula ya) y WaitForFirstConsumer (espera a que un pod lo use)
Revisá los eventos del PVC: kubectl describe pvc <nombre> muestra exactamente por qué no se vincula
El provisioner pod debe estar corriendo en kube-system para aprovisionar volúmenes dinámicamente

Ponele que subís un Deployment a tu cluster Kubernetes, le asignás un PVC, aplicás el YAML y de repente ves que el pod nunca entra en running. El evento dice “PersistentVolumeClaim is not bound”. Te metés en la descripción del PVC y está ahí, stuck en pending, sin moverse, no hay logs que digan qué pasó, solo una espera eterna (spoiler: esto sucede en producción constantemente). Eso sí, una vez que sabés dónde mirar, la solución es simple.

Qué es un PersistentVolumeClaim y por qué queda Pending

Un PersistentVolumeClaim (PVC) es una solicitud de almacenamiento en Kubernetes. Cuando lo creás, el cluster intenta vincularlo con un PersistentVolume (PV) disponible o provisionarlo dinámicamente usando una StorageClass. Si eso no sucede, el PVC queda en estado pending, esperando que la vinculación se complete.

La relación es bastante directa. El PVC dice “necesito 10GB de almacenamiento con acceso ReadWriteOnce” y Kubernetes busca un PV que cumpla esos requisitos. Si encuentra uno, vinculan y el PVC entra en bound. Si no, si algo falla en el aprovisionamiento dinámico o hay un conflicto de configuración, el PVC se queda esperando indefinidamente.

Causa #1: StorageClass No Existe o Es Incorrecto

persistentvolumeclaim pendiente kubernetes diagrama explicativo

Este es el clásico. Creás un PVC que referencia una StorageClass que nunca existió o cambió de nombre entre ambientes. El PVC no tiene nada que hacer, se queda pending y espera.

Para verificar qué StorageClasses tenés disponibles:

kubectl get storageclass

Si la clase que tu PVC solicita no está ahí, ese es el problema. Por ejemplo, tu PVC dice storageClassName: fast-ssd pero en tu cluster la StorageClass se llama “fast-storage” o “ssd-premium”. La solicitud va a pending porque Kubernetes no puede provisionar un volumen sin una clase válida.

Ojo: si no especificás storageClassName en absoluto, Kubernetes intenta usar la StorageClass por defecto, que quizás tampoco existe en tu setup. Verificalo con kubectl get storageclass y buscá cuál tiene default en su nombre. Más contexto en ejecución sin API externa.

Causa #2: volumeBindingMode — Immediate vs WaitForFirstConsumer

Acá es donde muchos se pierden. Las StorageClasses tienen un parámetro que se llama volumeBindingMode que dicta cuándo se vincula el volumen.

Si el modo es “Immediate”, Kubernetes intenta provisionar y vincular el volumen en el instante en que el PVC se crea. Si el modo es “WaitForFirstConsumer”, el cluster espera a que alguien use el PVC, un Pod típicamente, antes de hacer la vinculación.

¿Qué pasa? Si tu StorageClass usa WaitForFirstConsumer pero vos no creás el Pod que va a usar el PVC, el PVC se queda pending para siempre. Es una característica útil en clusters con múltiples zonas, porque evita provisionar un volumen en una zona si el Pod que lo necesita está en otra, pero si no sabés que existe, pinta como un bug.

Causa #3: Provisioner No Disponible o Caído

El provisioner es el componente responsable de crear volúmenes dinámicos. En AWS es el EBS provisioner, en GCP el GCE provisioner. Si el provisioner pod está crashed o no existe, los PVCs pending van a quedarse esperando para siempre.

Para verificar que los provisioners están corriendo:

kubectl get pods -n kube-system | grep provisioner

En AWS, buscá algo como “ebs-csi-controller”. En GCP, “gce-pd-csi-driver”. Si el pod no está en Running, tenés un problema. Los provisioners fallan por razones variadas: falta de credenciales en la cuenta de servicio, quota excedida en el cloud provider, VPC mal configurada, o simplemente una actualización que dejó las cosas rotas.

Cuando esto pasa, kubectl describe pvc te va a devolver algo tipo “waiting for a volume to be created” o “failed to provision volume”, dependiendo de cuán informativo sea tu provisioner.

Causa #4: Modos de Acceso y Afinidad de Nodos

No todos los tipos de almacenamiento soportan todos los modos de acceso. El modo ReadWriteOnce (RWO) significa que el volumen puede ser montado en lectura y escritura, pero en un solo nodo a la vez. El modo ReadWriteMany (RWX) permite múltiples nodos. El modo ReadOnlyMany es de solo lectura en varios nodos. Complementá con testing de volúmenes.

El problema: si pedís ReadWriteMany pero tu StorageClass solo provee almacenamiento en bloques, EBS por ejemplo, Kubernetes no puede cumplir la solicitud y el PVC queda pending.

Otra trampa es la afinidad de nodos. Si tu StorageClass está configurada para provisionar en la zona us-east-1a, pero tu Pod está corriendo en us-east-1b, hay un conflicto. El volumen se provisiona en una zona, el pod en otra, y el PVC puede quedar pending si la afinidad de nodo impide que se vinculen.

Cómo Diagnosticar: Comandos y Eventos

Primer paso, ver el estado del PVC:

kubectl get pvc

Te muestra una lista rápida. Si ves STATUS = “Pending”, seguís con:

kubectl describe pvc <nombre-del-pvc> -n <namespace>

Mirá la sección “Events” al final de la salida. Ahí está todo. Si dice “storageclass.storage.k8s.io not found”, el problema es la clase. Si dice “waiting for a volume to be created”, el provisioner está trabajando o falló internamente. Si dice algo como “no PersistentVolumes available”, tenés almacenamiento preaprovisionado pero insuficiente.

El comando kubectl get events -n <namespace> --sort-by='.lastTimestamp' también te muestra un timeline de lo que pasó en el namespace, lo cual ayuda a contextualizar el problema.

Soluciones Paso a Paso Por Causa

Para StorageClass faltante

Creá la clase que te falta. En AWS, un ejemplo básico:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: fast-ssd
provisioner: ebs.csi.aws.com
parameters:
 type: gp3
 iops: "3000"
 throughput: "125"

Aplicá, esperá 5 segundos, revisá que el PVC automáticamente pase a bound. Si no, deletea el PVC y recrealo, o deletea y recrea el Pod que lo usa si usás WaitForFirstConsumer.

Para provisioner caído

Revisá los logs del provisioner pod:

kubectl logs -n kube-system <provisioner-pod-name>

Vé qué pasó. Usualmente es falta de credenciales. Chequeá que la service account del provisioner tenga los permisos correctos en tu cloud provider.

Para modo de acceso incompatible

Cambiá tu solicitud. Si tu almacenamiento solo permite RWO, usá ese modo. Si necesitás RWX, usá un storage provider que lo soporte, como NFS o sistemas distribuidos tipo Ceph. Tema relacionado: interfaz de monitoreo visual.

Errores Comunes Que Comete Cualquiera

Suponer que el PVC se vinculará “en el futuro”

Muchos dejan un PVC pending pensando que “eventualmente” se resolverá solo. No. Si el PVC está pending, algo está roto ahora. Diagnosticalo de una vez.

No revisar la sección Events

Los Events de Kubernetes son el debugger de aplicaciones stateful. Ignorarlos es como programar sin logs. kubectl describe pvc te lo muestra todo.

Usar StorageClasses que otros no conocen

Si creás una StorageClass custom, documentala. Si mañana alguien más toca la configuración y la borra, todos los PVCs pending te esperan. Mantené una lista de classes disponibles accesible.

Prevención: Mejores Prácticas

Documentá qué StorageClasses tenés disponibles en tu cluster. Una línea en tu README es suficiente: “Tenemos ‘fast-ssd’ para cargas de IOPS alta y ‘standard’ para lo demás”. Así nadie crea un PVC apuntando a una clase fantasma.

Entendé el volumeBindingMode desde el principio. Si usás WaitForFirstConsumer, asegurate de que siempre creás el Pod que consume el PVC dentro del mismo tiempo razonable. No dejes PVCs huérfanos.

Validá tu YAML antes de aplicar. Una herramienta como kubeval o simplemente kubectl apply --dry-run=client te atrapa errores de configuración sin afectar el cluster.

Monitorea regularmente tus PVCs. Un job cron que ejecute kubectl get pvc -A y alerte si hay alguno en pending por más de 5 minutos es una buena línea de defensa. Si trabajás en infraestructura propia o en servicios como los que ofrece donweb.com, automatizar esta detección escala bien y te ahorra headaches. Te puede servir nuestra cobertura de automatización de ciclos de vida.

Preguntas Frecuentes

¿Qué significa que el PVC esté Pending?

Significa que Kubernetes no pudo vincular el PVC con un PersistentVolume disponible o falló al provisionarlo dinámicamente. El cluster está esperando que se cumpla la solicitud, pero algo en la configuración o los recursos disponibles lo impide.

¿Cómo sé si mi StorageClass existe?

Ejecutá kubectl get storageclass. Si no ves el nombre que tu PVC especifica en el campo storageClassName, ese es el problema. Comparalo contra el valor en tu PVC YAML.

¿WaitForFirstConsumer evita que los pods comiencen?

No exactamente. El Pod puede comenzar, pero el contenedor que necesita el volumen queda en estado ContainerCreating indefinidamente, porque el volumen no se provisiona hasta que el Pod realmente intenta montar el PVC. De hecho, muchas veces pinta como un hang, no como un error.

¿Qué pasa si deleteo un PVC que está Pending?

Se elimina. No recuperas datos (no había ninguno) y liberás la solicitud. El almacenamiento que se haya aprovisionado en el backend se libera, a menos que tengas una política de retención configurada.

¿El provisioner debe estar siempre corriendo en kube-system?

Sí, típicamente. Si está en otro namespace, tenés una configuración no estándar. En un cluster gestionado (EKS, GKE, AKS), el proveedor cloud mantiene los provisioners funcionando, así que raramente fallan.

Conclusión

Un PersistentVolumeClaim stuck en pending es frustrante pero tiene diagnóstico directo. Noventa de cada cien veces es una StorageClass que no existe, un provisioner caído, o un misunderstanding del volumeBindingMode. Con kubectl describe pvc ves el evento que explica exactamente qué falló. De ahí es solo arreglarlo.

La prevención es simple: documentá tus StorageClasses, validá YAML antes de aplicar, y monitorea regularmente tus PVCs. El time-to-resolution es corto si sabés qué buscar.