Увеличение томов PVC в StatefulSet Kubernetes

volumeClaimTemplates

The StatefulSet "nginx" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden

ss.yaml

apiVersion: v1

Примените в кластер:

Ожидаемый вывод:

Это создаёт StatefulSet с тремя репликами NGINX и PVC размером 1Gi для каждого Pod. В реальной среде размер данных может вырасти — и вам потребуется увеличить объём.

## Когда прямое изменение не сработает

Если вы отредактируете ss.yaml и измените volumeClaimTemplates.spec.resources.requests.storage на 10Gi, а затем выполните kubectl apply, вы получите ошибку (см. раздел выше). Это нормальное поведение — манифест StatefulSet в этом отношении иммутабелен.

## Ручное изменение размера PVC

Обходной путь — напрямую изменить каждый PVC, созданный на основе volumeClaimTemplates. После этого потребуется заставить Kubernetes фактически выполнить расширение тома — обычно это достигается временным освобождением PVC от контроллера StatefulSet и перезапуском подов.

Шаги:

1. Найдите PVC, связанные с вашим StatefulSet:

Пример вывода:

2. Отредактируйте каждый PVC и измените spec.resources.requests.storage на желаемый объём:

В редакторе найдите:

requests:
  storage: 10Gi

Сохраните и закройте редактор. Kubectl сообщит об успешном редактировании:

Повторите для остальных PVC.

3. Проверьте PV — провиженер должен отразить новый размер:

Пример:

Обратите внимание: PVC могут временно показывать старый размер, пока томы всё ещё примонтированы к запущенным подам. Расширение файловой системы внутри пода обычно выполняется после размонтирования/перемонтирования или перезапуска пода.

## Освобождение томов и воссоздание StatefulSet

Чтобы фактически применить увеличение, нужно освободить PVC от контроллера StatefulSet, не удаляя сами поды. Для этого удалите StatefulSet с флагом --cascade=orphan:

Это удалит объект StatefulSet, но не поды и не PVC. После этого поды продолжают работать, но уже не контролируются StatefulSet.

Далее обновите ss.yaml, чтобы volumeClaimTemplates указывал новый размер (например, 10Gi), и снова примените его:

Ожидаемый вывод:

Новый StatefulSet «заберёт» существующие поды, поскольку они удовлетворяют его селекторам и требованиям. Часто потребуется инициировать контролируемый rollout, чтобы поды были перезапущены по одному и файловые системы увидели новый размер:

Rollout будет выполняться последовательно (по одному Pod-у одновременно), что минимизирует простой.

После перезапуска проверьте PVC:

Они должны показать обновлённый размер:

Подключитесь внутрь пода и проверьте размер:

Внутри пода:

Файловая система показывает ожидаемые ~10 Gi.

## Ограничения и требования

- Драйвер хранения должен поддерживать динамическое расширение (allowVolumeExpansion). Начиная с Kubernetes v1.24 это стало общедоступной возможностью, но не все провайдеры или дистрибуции поддерживают её одинаково. Проверьте:

и убедитесь, что в колонке ALLOWVOLUMEEXPANSION стоит true для используемого StorageClass.

- Расширение блоковых томов обычно работает без проблем. Для расширения файловой системы внутри пода может потребоваться её размонтировать/перемонтировать или перезапустить под.

- Если том используется одновременно несколькими нодами в режиме, несовместимом с расширением, вы не сможете увеличить размер онлайн.

## Риски и смягчения

- Риск: человеческая ошибка при редактировании PVC приведёт к потере данных.
  - Смягчение: делайте snapshot/backup перед операцией, выполняйте изменения поочерёдно и проверяйте состояние PV/PVC.

- Риск: StorageClass не поддерживает расширение.
  - Смягчение: проверить поддержку заранее и подготовить план миграции томов (создание нового PV + синхронизация данных).

- Риск: несовместимость с облачным провайдером.
  - Смягчение: протестировать процедуру в тестовом кластере перед PROD.

## Побочные подходы и альтернативы

1. Миграция данных на новый PVC / PV

   - Создайте новый PVC с нужным размером.
   - Распакуйте или синхронизируйте данные (rsync, tar, копирование внутри кластера).
   - Обновите Deployment/StatefulSet для использования нового PVC (может потребовать создания нового StatefulSet и поочерёдного переключения).

   Плюсы: не зависит от allowVolumeExpansion. Минусы: сложнее и дольше.

2. Использовать CSI-операторы или кастомные контроллеры

   - Некоторые CSI-драйверы или операторы предоставляют дополнительные возможности по управлению томами и миграциям.

3. Планирование и мониторинг заполнения

   - Используйте метрики (Prometheus) и оповещения, чтобы заранее узнавать, что томы заполняются, и выполнять resize заранее.

## Пошаговый SOP для администратора (Playbook)

1. Подготовка
   - Убедитесь, что у вас есть бэкап/снимок данных.
   - Проверьте allowVolumeExpansion у StorageClass: `kubectl get sc`.
   - Оповестите команду о плановом окне.

2. Изменение PVC
   - Для каждого PVC выполните `kubectl edit pvc <имя>` и обновите `spec.resources.requests.storage`.
   - Подтвердите изменение: `kubectl get pv` — проверьте CAPACITY.

3. Освобождение StatefulSet
   - Выполните `kubectl delete statefulset --cascade=orphan `.

4. Обновление манифеста
   - Обновите volumeClaimTemplates в ss.yaml на новый размер.
   - Примените `kubectl apply -f ss.yaml`.

5. Rollout
   - Запустите `kubectl rollout restart statefulset `.
   - Мониторьте статус: `kubectl rollout status statefulset `.

6. Верификация
   - Для каждого пода: `kubectl exec -it  -- df -h `.
   - Проверьте приложения и метрики.

7. Откат (если необходимо)
   - Если обнаружены проблемы, восстановите данные из бэкапа и верните предыдущий манифест.

## Роль‑ориентированные контрольные списки

Администратор кластера

- Проверить allowVolumeExpansion в StorageClass.
- Сделать snapshot или бэкап.
- Координировать окно изменений.

DevOps / Разработчик

- Обновить ss.yaml с новым размером.
- Подтвердить, что приложение корректно перезагружается.

Storage‑администратор

- Подтвердить поддержку расширения в провайдере хранения.
- Проверить состояние PV после изменений.

## Быстрый чек-лист для тестирования (Test cases)

- После изменения PVC PV показывает новый CAPACITY.
- После перезапуска pod внутри df -h показывает ожидаемый размер.
- Нагрузка на приложение остаётся в допустимых пределах во время поочередного rollout.

## Полезные heuristics и ментальные модели

- Всегда работайте с одним PVC за раз в продакшене, если не уверены в проводимости процесса.
- Подход «orphan и reapply» минимизирует время, когда поды вовсе отсутствуют, т.к. они остаются запущенными.
- Хранение данных и контроль за их размерами — плановая задача мониторинга, а не реактивная операция.

## Troubleshooting — распространённые проблемы и решения

Проблема: PVC не расширился, PV остался прежнего размера.
- Возможная причина: драйвер хранения не поддерживает динамическое расширение.
- Решение: проверьте StorageClass, обратитесь к поставщику, используйте миграцию на новый PV.

Проблема: файл система внутри пода не показывает увеличение после расширения PV.
- Причина: файловая система не была расширена автоматически.
- Решение: перезапустите pod или выполните ручное расширение (например, resize2fs для ext4) внутри пода.

Проблема: при удалении StatefulSet с --cascade=orphan поды утрачивают нужные метаданные и не привязываются обратно.
- Решение: проверьте селекторы и labels в манифесте нового StatefulSet. Они должны совпадать с теми, что есть у существующих подов.

## Совместимость и миграция

Проверьте следующее перед операцией:

- StorageClass.allowVolumeExpansion = true
- Версия Kubernetes >= 1.24 (рекомендуется) для стабильного поведения расширения томов
- Документация облачного провайдера/CSI-драйвера на предмет известных ограничений

Если driver не поддерживает расширение:
- Рассмотрите миграцию данных на новый PVC с желаемым размером.
- Используйте инструменты синхронизации (rsync) или snapshot/restore.

## Мермад-диаграмма решения (decision tree)

## Краткое резюме

- StatefulSet не позволяет менять размер volumeClaimTemplates напрямую.
- Рабочий обход: отредактировать PVC, удалить StatefulSet с --cascade=orphan, обновить манифест и перезапустить rollout.
- Убедитесь, что StorageClass поддерживает allowVolumeExpansion. Всегда имейте резервную копию данных.

Важно: процесс требует аккуратности и тестирования в непроизводственной среде перед применением в продакшене.

## Глоссарий (1 строка каждого термина)

- PVC: PersistentVolumeClaim — запрос на постоянный том в Kubernetes.
- PV: PersistentVolume — реальный том, предоставленный кластером.
- StorageClass: класс хранения, описывающий провиженер и параметры PV.
- StatefulSet: контроллер Kubernetes для управляния stateful-приложениями.

---

Ниже приведены ключевые команды для быстрой работы:

Важно: перед операциями на продакшене делайте бэкап и тестируйте процедуру в staging.