PVC остался Pending: StorageClass, provisioner и WaitForFirstConsumer

Приложение не стартует, а PersistentVolumeClaim показывает Pending. Удаление и повторное создание заявки иногда только стирает полезные события. Сначала выясним, какой механизм должен предоставить хранилище и когда. Для некоторых StorageClass ожидание первого потребителя является нормальной частью выбора диска в нужной зоне.

Читаем заявку и события

kubectl -n demo get pvc data-api -o yaml
kubectl -n demo describe pvc data-api
kubectl get storageclass

Здесь data-api — имя PVC. Из spec выпишите storageClassName, accessModes, volumeMode и запрошенный объём. В Events ищите сообщения ожидания consumer, external provisioner и ошибки создания тома. Сам статус Pending объединяет несколько сценариев. Важно сохранить полный текст события и время, чтобы не спутать старую ошибку с текущим ожиданием.

Если storageClassName не указан, может использоваться default StorageClass. Явное пустое значение storageClassName: "" означает другой выбор: класс не запрашивается. Не считайте эти варианты эквивалентными. Когда default-класса нет, заявке может требоваться существующий подходящий PV или явный класс. Изменение дефолта всего кластера ради одной заявки влияет и на будущие приложения.

Проверяем, кто должен создать том

kubectl get storageclass fast -o yaml
kubectl get persistentvolume
kubectl -n demo get pods -o wide

Подставьте фактический класс вместо fast. Поле provisioner определяет драйвер. Само наличие StorageClass не устанавливает CSI-драйвер и не выдаёт ему права в облаке. Ошибки квоты, доступа и параметров диска ищите в событиях PVC, затем в журналах соответствующего CSI controller. Имена и namespace компонентов зависят от установленного драйвера, поэтому не перезапускайте случайный controller по совпадению слова storage.

Для статического PV проверьте класс, достаточный объём, режим доступа, volumeMode и отсутствие чужого claimRef. Существующий диск не становится подходящим только потому, что его размер больше заявки. При dynamic provisioning проверьте ограничения зоны и доступность выбранного типа диска. Успех создания cloud-объекта и его привязка к PVC — последовательные этапы, у каждого может быть своя ошибка.

Когда WaitForFirstConsumer ожидаем

Режим WaitForFirstConsumer откладывает привязку или создание тома до появления Pod, использующего PVC. Scheduler учитывает размещение приложения, чтобы диск оказался доступен нужному узлу. Если вы создали только PVC и ждёте Bound перед созданием Pod, возникает искусственное ожидание: потребитель как раз нужен для следующего шага.

apiVersion: v1
kind: Pod
metadata:
  name: storage-check
  namespace: demo
spec:
  containers:
    - name: check
      image: busybox:1.37
      command: ["sh", "-c", "sleep 3600"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: data-api

Этот диагностический Pod предназначен для отдельного учебного PVC. К рабочему тому его без согласования не подключают: режим доступа, владелец данных и активное приложение имеют значение. Пример показывает саму ссылку claimName. После появления потребителя смотрите события обоих объектов: PVC объясняет создание диска, Pod — ограничения размещения.

Потребитель есть, но прогресса нет

Если Pod запрашивает недоступную зону или несовместимые метки узлов, привязка может продолжать ждать. Сопоставьте nodeSelector, affinity и topology StorageClass. Не используйте spec.nodeName для обхода scheduler при WaitForFirstConsumer: scheduler тогда не участвует в нужном выборе, и PVC может остаться Pending. Для осознанного выбора узла используйте поддерживаемые ограничения размещения.

Когда PVC стал Bound, отдельно проверьте MountVolume и запуск контейнера. Связанный том ещё может не монтироваться из-за CSI, режима доступа или подключения к другому узлу. В таком случае возвращаться к настройке default StorageClass уже не нужно: этап привязки пройден. Успешная диагностика заканчивается конкретной записью, какое условие отсутствовало и какое событие подтвердило переход к следующему этапу.

Ещё по теме

• Pod завис в Pending: как читать события и найти нехватку ресурсов
• ConfigMap обновился, а приложение видит старое значение: env, volume и перезапуск

Продолжить изучение

Хотите увереннее разворачивать приложения и разбирать сбои в кластере? Сети, конфигурация, хранилища и обновления входят в программу «Kubernetes с нуля до PRO».