В Linux cgroups (контрольные группы) — это механизм ядра для управления системными ресурсами. Kubernetes использует cgroups, чтобы выделять контейнерам CPU и память, обеспечивать стабильную работу приложений и не допускать их взаимного влияния. С выходом Kubernetes v1.31 поддержка управления cgroup v1 перешла в режим сопровождения. Поддержка управления cgroup v2 стабильна с Kubernetes v1.25.

По сравнению с cgroup v1 версия cgroup v2 предлагает единую иерархию, более согласованный интерфейс и более надёжную основу для изоляции ресурсов и современных функций управления ими.

Команда VK Tech перевела статью о том, зачем Kubernetes переходит на cgroup v2, что меняется в управлении ресурсами и как подготовить узлы к миграции. 

Прекращение поддержки cgroup v1

Kubernetes объявил cgroup v1 устаревшим. Начиная с Kubernetes v1.35 параметр failCgroupV1 по умолчанию равен true, поэтому kubelet не запускается на узлах с cgroup v1 без изменения конфигурации. Администраторы могут временно задать failCgroupV1: false в файле конфигурации kubelet, но поддержка будет удалена в соответствии с политикой Kubernetes по прекращению поддержки. Дальнейшая работа отслеживается в KEP-5573: удаление поддержки cgroup v1.

Если вы используете версию ниже v1.35, перед обновлением переведите все Linux-узлы на cgroup v2 либо запланируйте временное переопределение failCgroupV1: false. Если у вас уже v1.35 или новее, убедитесь, что все Linux-узлы используют cgroup v2 или что переопределение сохранено намеренно. С настройками по умолчанию kubelet не запустится на узлах, которые остались на cgroup v1.

В кластерах под управлением kubeadm начиная с Kubernetes v1.35 эта проверка выполняется раньше и стала строже. Предварительная проверка SystemVerification из k8s.io/system-validators возвращает ошибку при выполнении kubeadm init, kubeadm join и kubeadm upgrade, если обнаруживает cgroup v1 при kubelet v1.35 или новее. Для более старых версий kubelet проверка по-прежнему выдаёт предупреждение. Подробности — в примечаниях к выпуску kubernetes/system-validators#1.12.1.

Чаще всего возникают вопросы о том, зачем переходить на cgroup v2, каковы преимущества и недостатки и что нужно учитывать при её использовании.

Ограничения cgroup v1 и улучшения в cgroup v2

Документация ядра Linux описывает оба интерфейса:

Перечислим некоторые известные проблемы.

Память active_file не считается доступной

Kubelet считает память active_file недоступной для освобождения. Поэтому при интенсивном вводе-выводе большой страничный кэш может приводить к тому, что kubelet сообщает о нехватке памяти и вытесняет поды. Это известная проблема kubelet (kubernetes/kubernetes#43916), и сам по себе переход на cgroup v2 не меняет расчёт. Документированный обходной путь — измерить подходящий объём памяти и задать одинаковые requests и limits для контейнеров с интенсивным вводом-выводом.

Обновления Memory QoS в Kubernetes v1.36

Memory QoS появилась в Kubernetes v1.22 как альфа-функция и была обновлена в v1.27. В v1.36 она по-прежнему имеет статус альфа, но теперь разделяет троттлинг и резервирование памяти и добавляет многоуровневую защиту памяти:

Memory QoS доступна только на Linux-узлах с cgroup v2. Она использует контроллер памяти cgroup v2: memory.high отвечает за троттлинг, а memory.min и memory.low обеспечивают жёсткую и мягкую защиту при включённом многоуровневом резервировании. В cgroup v1 такая модель защиты недоступна.

  • Включение feature gate MemoryQoS активирует троттлинг через memory.high для контейнеров класса Burstable. Порог рассчитывается на основе request, limit и memoryThrottlingFactor, который по умолчанию равен 0.9.

  • По умолчанию используется memoryReservationPolicy: None. При этой политике значения memory.min и memory.low не записываются.

  • Политика memoryReservationPolicy: TieredReservation сопоставляет requests памяти подов класса Guaranteed с memory.min (жёсткая защита), а подов класса Burstable — с memory.low (мягкая защита). Поды класса BestEffort не получают ни той, ни другой защиты.

  • Kubelet предоставляет альфа-метрики суммарного объёма резервирования memory.min и memory.low на узле.

  • Рекомендуется ядро версии 5.9 или новее. На более старых ядрах освобождение памяти через memory.high может вызывать известный livelock. Начиная с v1.36 kubelet записывает предупреждение в журнал, если Memory QoS включена на ядре, подверженном этой проблеме.

Пример включения многоуровневой защиты:

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
featureGates:
  MemoryQoS: true
memoryReservationPolicy: TieredReservation
memoryThrottlingFactor: 0.9

В целом проект Kubernetes не рекомендует включать альфа-функции в продакшене. Если вы всё же считаете Memory QoS с многоуровневым резервированием полезной для своей платформы в продакшене, перед включением feature gate TieredReservation обязательно протестируйте конфигурацию и учтите объём жёстко зарезервированной памяти. Актуальное соответствие классов QoS Kubernetes параметрам cgroup v2 приведено в документации Pod QoS.

Обработка OOM на уровне контейнера

На узлах с cgroup v2 параметр singleProcessOOMKill у kubelet по умолчанию равен false. Поэтому kubelet устанавливает memory.oom.group для cgroup каждого контейнера: при OOM все процессы контейнера завершаются вместе. Это позволяет избежать ситуации, когда многопроцессный контейнер продолжает работать лишь частично. Задавайте singleProcessOOMKill: true, только если вам нужно поведение, совместимое с cgroup v1, при котором ядро может завершать процессы по одному. Описание параметра приведено в справочнике KubeletConfiguration.

Такое поведение ограничено cgroup контейнера и не распространяется на весь под. Отдельно существует административный интерфейс cgroup.kill: запись 1 в него отправляет SIGKILL всем процессам этой cgroup и вложенных групп. Он не настраивает поведение при OOM. Контроллер памяти cgroup v2 также предоставляет счётчики memory.events, которые могут отслеживать системы мониторинга и OOM-менеджеры в пользовательском пространстве.

Поддержка rootless-режима

В cgroup v1 делегирование контроллеров менее привилегированным контейнерам может быть опасным.

В отличие от cgroup v1, cgroup v2 официально поддерживает делегирование. Большинство реализаций rootless-контейнеров использует systemd для делегирования контроллеров v2 пользователям без прав root.

Этот механизм делегирования не связан с пространствами имён пользователей для подов Kubernetes, которые сопоставляют пользователей контейнера с непривилегированными пользователями хоста. Поддержка пространств имён пользователей для подов стала стабильной в Kubernetes v1.36. Перед включением проверьте требования к файловой системе, ядру и средам выполнения CRI и OCI.

Что ещё?

  1. Возможности, связанные с eBPF:

    • В cgroup v1 доступом к устройствам управляют через интерфейсные файлы.

    • У контроллера устройств cgroup v2 нет интерфейсных файлов: он реализован на основе cgroup BPF.

    • Cilium подключает программы BPF к cgroup для балансировки нагрузки на уровне сокетов. По умолчанию корневая cgroup находится в /run/cilium/cgroupv2.

  2. Pressure Stall Information (PSI) показывает конкуренцию за CPU, память и ввод-вывод на уровне узла, пода и контейнера. В поддерживаемых кластерах kubelet предоставляет PSI по умолчанию: KubeletPSI имеет статус stable и принудительно включён. Для PSI нужны cgroup v2, Linux 4.20 или новее, CONFIG_PSI=y и ядро, загруженное без psi=0. Kubelet предоставляет эти данные через Summary API и /metrics/cadvisor.

  3. При миграции обновите ПО, которое напрямую читает файловую систему cgroup. В рекомендациях по миграции указаны cAdvisor v0.43.0 или новее, а также совместимые версии Java, Node.js и automaxprocs.

Преобразование веса CPU в новых версиях сред выполнения OCI

В cgroup v1 используется cpu.shares, в cgroup v2 — cpu.weight. Новые версии сред выполнения OCI применяют улучшенное нелинейное преобразование, которое сохраняет приоритет по умолчанию и позволяет точнее различать небольшие значения requests CPU. Изменение реализовано в среде выполнения OCI, а не в Kubernetes, и доступно в crun v1.23 и runc v1.3.2.

После обновления среды выполнения может потребоваться обновить инструменты мониторинга или применения политик, которые рассчитывают точные значения cpu.weight. Формула, примеры и вопросы совместимости рассмотрены в статье «Новое преобразование CPU shares cgroup v1 в CPU weight cgroup v2».

Изменение ресурсов без пересоздания пода

Вертикальное масштабирование подов без пересоздания стало стабильным в Kubernetes v1.35. В Kubernetes v1.36 вертикальное масштабирование ресурсов уровня пода без пересоздания включили по умолчанию как бета-функцию. Kubelet согласует изменения в cgroup пода и контейнеров: при увеличении ресурсов сначала создаёт запас на уровне пода, а затем повышает limits контейнеров; при уменьшении сначала ограничивает контейнеры, а затем снижает общий лимит пода. Для точного применения совокупных ограничений этой функции v1.36 требуется cgroup v2.

Переход на cgroup v2

Требования

Чтобы использовать cgroup v2, нужна версия Kubernetes с поддержкой управления cgroup v2. Эта поддержка стабильна с Kubernetes v1.25 и доступна во всех поддерживаемых версиях Kubernetes.

  • Хотя бы один Linux-узел: cgroup существует только в Linux.

  • В установленной ОС должна быть включена cgroup v2.

  • Ядро версии 5.8 или новее; для Memory QoS рекомендуется 5.9 или новее.

  • Среда выполнения контейнеров должна поддерживать cgroup v2. Например:

    • containerd v1.4 или новее поддерживает cgroup v2; для автоматического определения драйвера cgroup используйте containerd v2.0 или новее.

    • CRI-O v1.20 или новее.

  • Kubelet и среда выполнения контейнеров должны использовать корректно настроенный драйвер cgroup. См. раздел «Настройка драйвера cgroup kubelet в соответствии с драйвером среды выполнения контейнеров».

Пока можно снова включить cgroup v1. Проект Kubernetes рекомендует cgroup v2, но в Kubernetes 1.36 (текущем выпуске) cgroup v1 по-прежнему поддерживается как резервный вариант. Его удаление запланировано на Kubernetes v1.38. Если вы используете старый кластер, запланируйте миграцию. При развёртывании нового кластера с Linux-узлами выбирайте cgroup v2. В обоих случаях изучите документацию Kubernetes по средам выполнения и, если применимо, матрицу совместимости containerd.

Разворачивайте кластеры Kubernetes с Managed Containers

Автоматизируйте деплой
и снижайте затраты на инфраструктуру
до 60%

Попробовать

Обновления ядра, связанные с cgroup v2

Когда Kubernetes впервые анонсировали в 2014 году, существовала только cgroup v1. Поддержка управления cgroup v2 впервые появилась в ядре Linux 4.5, выпущенном в 2016 году.

  • В Linux 4.5 поддерживались контроллеры cgroup v2 io, memory и pids.

  • В Linux 4.15 появилась поддержка контроллера cpu в cgroup v2.

  • Поддержка Pressure Stall Information (PSI) появилась в Linux 4.20.

  • Проект Kubernetes не рекомендует использовать cgroup v2 с ядрами Linux ниже 5.2: в них нет механизма приостановки задач на уровне cgroup.

  • В документации Kubernetes минимальной версией ядра для cgroup v2 указана 5.8. Файл cpu.stat корневой cgroup с общесистемными данными появился в Linux 5.8.

  • Исправление livelock при работе с memory.high, на которое опирается Memory QoS, доступно в Linux 5.9 и новее.

  • memory.peak появился в Linux 5.19.

Настройка драйвера cgroup

Настройте драйвер cgroup kubelet в соответствии с драйвером cgroup среды выполнения контейнеров.

Если кластером управляет kubeadm, проект Kubernetes рекомендует драйвер cgroup systemd, поскольку kubeadm управляет kubelet как службой systemd. Если вы используете другой инструмент управления кластером, обратитесь к его документации.

Если можно выбрать любой из вариантов, я рекомендую драйвер systemd.

Независимо от выбранного инструмента kubelet автоматически пытается определить драйвер cgroup, рекомендуемый средой выполнения. Для этого среда выполнения должна реализовывать CRI RPC RuntimeConfig, как, например, containerd v2.0+ или CRI-O v1.28+.

Если среда выполнения контейнеров поддерживает cgroup v2, но не поддерживает автоматическое определение драйвера cgroup, его можно задать вручную в файле конфигурации kubelet. Например:

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd

Автоматическое определение драйвера cgroup среды выполнения через CRI, описанное в KEP-4033, стало стабильным в Kubernetes v1.34. Для него нужна среда выполнения, которая реализует CRI RPC RuntimeConfig: containerd v2.0+ или CRI-O v1.28+. Если эта возможность доступна, kubelet использует значение, полученное от среды выполнения, вместо cgroupDriver из своей конфигурации.

Инструменты и команды для диагностики

Полезные инструменты и команды для работы с cgroups:

  • stat -fc %T /sys/fs/cgroup/ — проверяет, включена ли cgroup v2. Команда возвращает cgroup2fs.

  • systemctl list-units 'kube*' --type=slice или --type=scope — выводит связанные с Kubernetes юниты, которые systemd сейчас держит в памяти.

  • bpftool cgroup list /sys/fs/cgroup/* — выводит все программы, подключённые к cgroup CGROUP.

  • systemd-cgls /sys/fs/cgroup/* — рекурсивно показывает содержимое контрольных групп.

  • systemd-cgtop — показывает контрольные группы с наибольшим потреблением ресурсов.

  • tree -L 2 -d /sys/fs/cgroup/kubepods.slice — показывает каталоги cgroup, связанные с подами.

Как проверить, применилось ли ограничение CPU или памяти пода к файлу cgroup?

Начните с объекта API и переходите к узлу. Определите узел, затем сравните запрошенные ресурсы в spec с применёнными значениями в status: после изменения ресурсов без пересоздания пода они могут различаться.

kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{.spec.nodeName}{"\n"}'
kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{range .spec.containers[*]}{.name}{" spec\t"}{.resources}{"\n"}{end}'
kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{range .status.containerStatuses[*]}{.name}{" status\t"}{.resources}{"\n"}{end}'

Следующие команды выполняются на найденном узле от имени root, с драйвером cgroup systemd и cgroup v2. Для них также нужен jq. Однозначно определите контейнер по меткам kubelet: одного имени недостаточно, поскольку на узле оно может быть неуникальным. Если контейнер не запущен, используйте crictl ps -a:

CONTAINER_ID=$(crictl ps \
  --label io.kubernetes.pod.namespace=<namespace> \
  --label io.kubernetes.pod.name=<pod-name> \
  --name <container-name> -q | head -n1)
# Представление OCI (не имена полей protobuf из CRI)
crictl inspect "$CONTAINER_ID" | jq '.info.runtimeSpec.linux.resources'
# Путь cgroup в ядре для этого контейнера
PID=$(crictl inspect "$CONTAINER_ID" | jq -r '.info.pid')
CGROUP="/sys/fs/cgroup$(awk -F: '$1=="0"{print $3}' /proc/$PID/cgroup)"
cat "$CGROUP/cpu.weight"   # request.cpu → shares → weight; это не ограничение
cat "$CGROUP/cpu.max"      # limit.cpu в виде "quota period"; без ограничения указано "max <period>"
cat "$CGROUP/memory.max"   # limit.memory; без ограничения указано "max"
# cgroup уровня пода (родительский slice), используется ресурсами уровня пода
cat "$(dirname "$CGROUP")/cpu.max" "$(dirname "$CGROUP")/memory.max"
# Присутствуют, когда включена MemoryQoS
cat "$CGROUP/memory.high" "$CGROUP/memory.min" "$CGROUP/memory.low"
SCOPE=$(basename "$CGROUP")
systemctl show "$SCOPE" \
  -p CPUWeight -p CPUQuotaPerSecUSec -p CPUQuotaPeriodUSec -p MemoryMax

Если среда выполнения использует драйвер systemd, не воспринимайте info.runtimeSpec.linux.cgroupsPath как путь в файловой системе. Это путь юнита systemd в формате slice:runtime:id, а не каталог в /sys/fs/cgroup.

Ожидаемое соответствие на каждом уровне:

  • Kubernetes: spec.containers[*].resources содержит запрошенные значения, status.containerStatuses[*].resources — значения, применённые после изменения ресурсов без пересоздания. Ресурсы уровня пода находятся в spec.resources и родительском slice пода.

  • CRI (kubelet → среда выполнения): cpu_shares, cpu_quota, cpu_period, memory_limit_in_bytes, а также unified для Memory QoS. Эти имена полей protobuf сохраняют стиль cgroup v1 даже при использовании v2. Команда crictl inspect не показывает их: она выводит спецификацию OCI, которую среда выполнения сформировала на их основе.

  • Спецификация OCI: linux.resources.cpu.{shares,quota,period}, linux.resources.memory.limit и linux.resources.unified. Среда выполнения преобразует shares, quota и period в файлы cgroup v2. После обновления crun или runc формула преобразования shares в weight может измениться. См. раздел «Преобразование веса CPU в новых версиях сред выполнения OCI».

  • Scope systemd: CPUWeight, CPUQuotaPerSecUSec, CPUQuotaPeriodUSec, MemoryMax. Значения без ограничения или без явной настройки часто отображаются как [not set] или infinity.

  • cgroupfs: cpu.weight рассчитывается из request CPU; даже если request не задан, используется значение по умолчанию — 2 shares. Файлы cpu.max и memory.max находятся в scope контейнера. Memory QoS добавляет memory.high, memory.min и memory.low.

Дополнительные материалы