Хуки жизненного цикла контейнера в Kubernetes

Коротко: хуки жизненного цикла — лёгкий способ выполнять команду или отправлять HTTP‑запрос внутрь контейнера при его создании (PostStart) и перед остановкой (PreStop). Хуки вызываются «по крайней мере один раз», должны быть идемпотентными и быть максимально простыми; при ошибке они убивают контейнер. Для надёжной подготовки контейнера рассмотрите initContainers и проверочные пробы (readiness/liveness).

Быстрые ссылки

• Доступные хуки
• Определение обработчиков хуков
• HTTP‑обработчики
• Отладка обработчиков
• Что важно учитывать
• Альтернативы и лучшие практики
• Контрольный список и сценарии тестирования
• Заключение

Kubernetes позволяет реагировать на создание и завершение контейнера внутри Pod, выполняя в контейнере команду или делая HTTP‑запрос к локальному эндпоинту. Хуки часто используют для логирования событий, запуска очистки или фоновых задач после появления Pod в кластере. В этой статье объясняется, как прикреплять обработчики хуков к Pod и какие нюансы стоит учитывать.

Доступные хуки

Текущие релизы Kubernetes поддерживают два хука жизненного цикла контейнера:

• PostStart — обработчик вызывается сразу после создания нового контейнера.
• PreStop — обработчик вызывается непосредственно перед тем, как Kubernetes инициирует завершение контейнера.

Каждый хук можно реализовать двумя механизмами:

• exec — выполнить указанную команду внутри контейнера.
• httpGet — сделать HTTP GET‑запрос на URL внутри контейнера.

Замечания:

• Хуки не получают аргументов от Kubernetes.
• В одном контейнере поддерживается только один обработчик на каждый хук; нельзя вызывать несколько точек одновременно или комбинировать exec и httpGet в одном и том же хуке.

Определение обработчиков хуков

Обработчики хуков задаются в манифесте Pod в поле containers.lifecycle. В нём можно определить postStart и preStop.

Ниже — простой Pod, который при старте контейнера записывает сообщение в файл /startup_message.

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-hooks
spec:
  containers:
  - name: pod-hook-container
    image: nginx:latest
    lifecycle:
      postStart:
        exec:
          command: ["/bin/sh", "-c", "echo STARTED > /startup_message"]

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

$ kubectl apply -f pod.yaml

Получите shell внутри контейнера:

$ kubectl exec --stdin --tty pod/pod-with-hooks -- sh

Проверьте содержимое файла:

$ cat /startup_message

Вы увидите:

STARTED

Это подтверждает, что hook выполнился успешно. Exec‑хук считается успешным, если команда завершилась с кодом 0.

HTTP‑обработчики

HTTP‑обработчик настраивается заменой exec на httpGet. Поддерживаются только HTTP GET‑запросы.

Пример, в котором Kubernetes делает GET на /startup порта 80:

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-hooks
spec:
  containers:
  - name: pod-hook-container
    image: nginx:latest
    lifecycle:
      postStart:
        httpGet:
          path: /startup
          port: 80

Поле httpGet также принимает scheme и host для дополнительной настройки запроса:

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-hooks
spec:
  containers:
  - name: pod-hook-container
    image: nginx:latest
    lifecycle:
      preStop:
        httpGet:
          path: /shutdown
          scheme: HTTPS
          port: 443

HTTP‑хук считается успешным, если код ответа находится в диапазоне 200–299.

Отладка обработчиков

Логи хуков не собираются вместе с обычными логами Pod, поэтому вы не увидите вывод exec‑команд в kubectl logs. Хуки управляются отдельно от самого контейнера.

Чтобы отладить проблемы с хуками, просматривайте историю событий Pod: неудачные вызовы помечаются как FailedPostStartHook или FailedPreStophook. Сообщение об ошибке обычно содержит детальное объяснение.

Например, добавим Pod с некорректной командой:

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-hooks
spec:
  containers:
  - name: pod-hook-container
    image: nginx:latest
    lifecycle:
      postStart:
        exec:
          command: ["missing-command"]

В результате Pod может войти в цикл перезапусков. Посмотрите события:

$ kubectl describe pod/pod-with-hooks

В части Events вы увидите строки наподобие:

Warning FailedPostStartHook 10s kubelet Exec lifecycle hook ([missing-command]) for Container "pod-hook-container" in Pod "pod-with-hooks" failed - error: command 'missing-command' exited with 126: , message: "OCI runtime exec failed: exec failed: container_linux.go:380: starting container process caused: exec: \"missing-command\": executable file not found in $PATH: unknown"

Это означает, что команда не найдена внутри контейнера; ошибка привела к убийству контейнера и циклу BackOff.

Что важно учитывать

Ниже перечислены ключевые ограничения и частые ловушки при работе с хуками.

• Хуки могут вызываться более одного раза. Kubernetes гарантирует «at least once». Обработчики должны быть идемпотентными.
• Неудачные хуки убивают контейнер. Убедитесь, что команды и HTTP‑эндпоинты надёжны и не зависят от недоступных ресурсов.
• PostStart гонится с ENTRYPOINT. Kubernetes вызывает PostStart асинхронно — ваш ENTRYPOINT может завершиться до вызова или параллельно. Не полагайтесь на тот факт, что PostStart выполнится до старта основного процесса.
• PreStop блокирует завершение контейнера до окончания работы хука, но не дольше срока “terminationGracePeriodSeconds”. По истечении grace period контейнер будет завершён в любом случае.
• PreStop не вызывается для контейнеров, которые естественно завершились с кодом 0. Хук запускается при удалении Pod, исчерпании ресурсов, провале probe и т. п.

Влияние на состояние Pod:

• Pod не помечается как Running, пока завершился PostStart. Это может задержать переход в состояние Running.
• Pod может оставаться в Terminating, пока выполняется PreStop.

Важно: делайте хуки короткими и независимыми — лучше удалять тяжёлые операции в отдельных фоновых задачах.

Когда хуки не подходят и альтернативы

Хуки подходят для простых уведомлений и кратких локальных действий. Но есть ситуации, когда стоит выбрать альтернативы:

• Если нужно гарантированно дождаться готовности зависимостей — используйте initContainers или readinessProbe.
• Для долгих фоновых задач — вынесите их в отдельный sidecar или Job, чтобы не блокировать жизненный цикл контейнера.
• Если нужно аккуратно завершать распределённые ресурсы в кластере — сочетайте PreStop с контроллером, слушающим события удаления Pod, или используйте finalizer на уровне Kubernetes API.

Короткая сравнительная таблица:

• InitContainer: синхронная подготовка окружения перед основным контейнером.
• Readiness/Liveness probes: периодические проверки доступности и здоровья приложения.
• Sidecar/Job: долгие фоновые или распределённые задачи.

Практическое руководство: чеклист и SOP для хуков

Чеклист перед прикреплением хуков:

1. Определите цель хука (лог, сигнал, очистка, синхронизация).
2. Проверьте, доступна ли команда/эндпоинт внутри образа.
3. Сделайте команду/эндпоинт идемпотентным.
4. Убедитесь, что время выполнения короче, чем terminationGracePeriodSeconds (для PreStop).
5. Не зависеть от внешних недоступных сервисов в момент старта контейнера.
6. Добавьте тесты и сценарии отказа.

Стандартная процедура (SOP) добавления хука:

1. Локально протестировать команду в контейнере: docker run –rm -it IMAGE sh
2. Добавить lifecycle в манифест и применить в тестовом неймспейсе.
3. Наблюдать события kubectl describe pod и состояние Pod.
4. При ошибках анализировать FailedPostStartHook / FailedPreStophook.
5. При стабильности переносить в продуктив с контролируемым rollout.

Критерии приёмки

• PostStart: контейнер становится Running и /startup_message (или другой индикатор) присутствует.
• PreStop: при удалении Pod внешний ресурс получает сигнал и выполняет предусмотренные действия.
• Отсутствие долгих BackOff или постоянных ошибок в событиях Pod.

Сценарии тестирования и приёмочные тест-кейсы

1. Успешный exec PostStart
   • Действие: команда echo создаёт файл. Ожидаемый результат: файл присутствует.
2. Неудачный exec PostStart
   • Действие: указана несуществующая команда. Ожидаемый результат: событие FailedPostStartHook, контейнер перезапускается.
3. Идемпотентность PostStart
   • Действие: PostStart выполняется дважды. Ожидаемый результат: побочных эффектов не наблюдается.
4. PreStop блокирует завершение
   • Действие: PreStop делает sleep 10, terminationGracePeriodSeconds=30. Ожидаемый результат: Pod ожидает 10 секунд, затем завершается.
5. PreStop превышает grace period
   • Действие: PreStop делает sleep 40, terminationGracePeriodSeconds=30. Ожидаемый результат: контейнер принудительно завершён после grace period.
6. HTTP‑hook с кодом 500
   • Действие: httpGet возвращает 500. Ожидаемый результат: событие Failed*Hook и поведение согласно политике перезапуска.

Риски и способы минимизации

Риски:

• Долгие или зависающие хуки блокируют жизненный цикл и приводят к зависанию Pod.
• Хуки, зависящие от сетевых сервисов, могут провалиться на старте.
• Неидемпотентные хуки вызывают неконсистентное состояние при повторных вызовах.

Митигаторы:

• Держите хуки короткими и локальными.
• Встраивайте таймауты и проверки входных условий.
• Делайте операции идемпотентными и безопасными при повторных вызовах.
• Для долгих операций используйте sidecar или Job и не блокируйте основной контейнер.

Практические советы и эвристики

• Правило простоты: если установка занимает >10 секунд — вынесите её из PostStart.
• Default: используйте exec для локальных коротких команд и httpGet для сигналов к приложению.
• Разделение ответственности: initContainers для подготовки, PostStart для уведомлений.
• Локальная отладка: запуск контейнера вручную и выполнение команды из манифеста — быстрый способ проверить доступность инструментов внутри образа.

Пример шаблонов и фрагментов (cheat sheet)

Шаблон PostStart — exec:

lifecycle:
  postStart:
    exec:
      command: ["/bin/sh", "-c", "/usr/local/bin/init-script || true"]

Шаблон PreStop — httpGet с HTTPS:

lifecycle:
  preStop:
    httpGet:
      path: /shutdown
      scheme: HTTPS
      port: 8443

Идемпотентный PostStart (псевдологика):

if [ ! -f /startup_done ]; then
  do_one_time_setup && touch /startup_done
fi

Локальные особенности и советы для русскоязычных команд

• При создании образов для производства проверяйте наличие всех утилит (sh, curl, wget) и их расположение в PATH.
• Для корпоративных образов соблюдайте внутренние требования безопасности: не храните секреты в командах хуков, используйте сервисные аккаунты и секреты Kubernetes.
• Если ваша CI/CD использует прокси или ограниченный доступ в сеть, тестируйте httpGet‑хуки в изолированной среде.

Заключение

Хуки жизненного цикла — полезный инструмент для простых действий при старте и остановке контейнера: уведомлений, лёгкой инициализации и сигналов. Но они не заменяют initContainers, readiness/liveness probes или отдельные фоновые сервисы для сложных и долгих операций. Следуйте принципам простоты, идемпотентности и имеющейся архитектуры: короткие, локальные и понятные хуки помогают избежать неожиданных перезапусков и блокировок Pod.

Важно: всегда тестируйте хуки в контролируемом окружении и наблюдайте за событиями Pod через kubectl describe.

Ключевые темы для дальнейшего чтения: initContainers, readinessProbe, livenessProbe, finalizers, graceful shutdown.