CrashLoopBackOff в kubectl: причины и способы исправления

Что означает ошибка CrashLoopBackOff

CrashLoopBackOff — это не код ошибки в классическом понимании, а состояние пода (Pod) в Kubernetes. Оно означает, что контейнер внутри пода постоянно завершается (крашится), а kubelet (агент на ноде) срабатывает механизм экспоненциальной задержки (back-off) между попытками перезапуска.

Вы увидите это состояние при выполнении команды:

kubectl get pods

В колонке STATUS будет CrashLoopBackOff, а в RESTARTS — постоянно увеличивающееся число.

Полный текст события (из kubectl describe pod) обычно выглядит так:

  State:          Waiting
    Reason:       CrashLoopBackOff
  Last State:    Terminated
    Reason:       Error
    Exit Code:    1
    Started:      ...
    Finished:     ...

Причины возникновения

Состояние CrashLoopBackOff почти всегда вызвано тем, что процесс внутри контейнера завершается с ненулевым кодом возврата (обычно 1 или 137). Основные причины:

1. Ошибка в самом приложении: Непредвиденное исключение в коде, ошибка конфигурации, отсутствие обязательного файла или переменной окружения. Контейнер запускается, приложение падает.
2. Некорректная команда запуска (CMD/ENTRYPOINT): В Dockerfile или спецификации Pod'а указана команда, которая завершается сразу (например, запуск скрипта без exec или запуск фонового процесса без wait).
3. Нехватка ресурсов (OOMKilled): Контейнеру не хватает оперативной памяти, и ядро ноды его убивает. В логах и событии будет Reason: OOMKilled и Exit Code: 137.
4. Проблемы с правами доступа: Приложение пытается записать в защищённую директорию (например, /root), или не хватает прав на чтение файла.
5. Некорректно настроенные health-проб (livenessProbe): Проба (например, HTTP GET) постоянно возвращает неуспешный ответ, и kubelet убивает контейнер, даже если приложение в целом работает.
6. Отсутствие ожидаемого фонового процесса: Приложение запускается, порождает дочерний процесс и завершается, оставляя дочерний процесс "сиротой", который затем уничтожается.

Способы решения

Способ 1: Анализ логов и событий пода

Это первый и самый важный шаг. Команды ниже дадут точные указания на причину.

1. Посмотрите детальную информацию о поде:

   kubectl describe pod <имя-вашего-pod>
   

   
   Прокрутите секцию Events вниз. Ищите последние события типа Failed или BackOff. Обратите внимание на поля Reason и Message. Также в секции Containers -> <имя-контейнера> -> State будут указаны Last State (последнее состояние) и Reason (например, Error, OOMKilled).
2. Получите логи контейнера:
   • Логи последнего упавшего экземпляра (самые важные):

     kubectl logs <имя-вашего-pod> --previous
     

   • Логи текущего (возможно, только что запустившегося) контейнера:

     kubectl logs <имя-вашего-pod>
     

   • Если в поде несколько контейнеров, укажите имя контейнера: kubectl logs <pod-name> -c <container-name> --previous.
   
   На что смотреть в логах: Исключения (Java, Python, Node.js), сообщения permission denied, connection refused, file not found, OutOfMemoryError, Killed. Последние 5-10 строк часто содержат суть.

Способ 2: Проверка и корректировка ресурсов (Memory/CPU)

Если в kubectl describe pod или логах есть упоминание OOMKilled или Exit Code: 137, проблема, скорее всего, в нехватке памяти.

1. Временно увеличьте лимит памяти в манифесте YAML пода:

   spec:
     containers:
     - name: my-app
       image: my-image
       resources:
         limits:
           memory: "512Mi"   # Увеличьте, например, до 1Gi
         requests:
           memory: "256Mi"
   

2. Примените изменения:

   kubectl apply -f ваш-манифест.yaml
   

3. Если контейнер стабильно работает — проблема была в лимитах. Оптимизируйте приложение или установите реалистичные лимиты.

Способ 3: Проверка и исправление команды запуска (CMD/ENTRYPOINT)

Контейнер должен запускать foreground-процесс. Если ваш скрипт-точка входа (entrypoint.sh) запускает демон в фоне (&) и завершается, контейнер умрёт.

Неправильно (в entrypoint.sh):

#!/bin/sh
my-background-service &  # Запускает в фоне и завершает скрипт

Правильно:

#!/bin/sh
exec my-background-service  # exec заменяет shell процессом и не возвращает управление

Или, если нужно запустить несколько процессов, используйте менеджер процессов (например, tini или supervisord).

Способ 4: Временное отключение или проверка health-пробов

Некорректный livenessProbe — частая причина, особенно на ранних этапах разработки.

1. Временно отключите пробу в манифесте пода, закомментировав её секцию:

   # livenessProbe:
   #   httpGet:
   #     path: /health
   #     port: 8080
   #   initialDelaySeconds: 30
   #   periodSeconds: 10
   

2. Примените манифест и проверьте, исчез ли CrashLoopBackOff.
3. Если проблема ушла — настройте пробу правильно:
   • Увеличьте initialDelaySeconds, давая приложению время на запуск.
   • Убедитесь, что path и port корректны и сервис действительно отвечает 2xx/3xx на этот эндпоинт.
   • Для приложений с долгой инициализацией используйте readinessProbe для контроля готовности принимать трафик, а livenessProbe — только для жизнеспособности.

Способ 5: Проверка переменных окружения и конфигурационных файлов

Убедитесь, что все обязательные переменные окружения (env) и тома (volumes/configMap/secret) правильно указаны и доступны внутри контейнера.

1. Проверьте, что переменные передаются:

   kubectl exec <имя-pod> -- printenv | grep -i <имя-важной-переменной>
   

2. Если используется ConfigMap или Secret, проверьте его существование и данные:

   kubectl get configmap <имя-configmap> -o yaml
   

3. Проверьте права на смонтированные тома, если контейнер должен в них писать.

Профилактика

• Всегда проверяйте логи (kubectl logs --previous) при первом запуске нового пода.
• Начинайте с адекватных лимитов ресурсов. Используйте kubectl top pod для мониторинга фактического потребления.
• Корректно настраивайте health-проб. initialDelaySeconds должен превышать время холодного старта приложения.
• Используйте restartPolicy: OnFailure для Jobs, а не Always, чтобы избежать бесконечных циклов при ошибках в задачах.
• Собирайте образы с USER без прав root, если это возможно, и настройте права на директории (chown) на этапе сборки образа, а не в entrypoint.
• Тестируйте образ локально (docker run --rm <image> <command>) перед деплоем в Kubernetes, чтобы отделить проблемы с образом от проблем с оркестрацией.