🔧 Отладка в Kubernetes
Сломанный под почти всегда сам говорит, что с ним не так: в статусе, в событиях и в коде выхода прошлого контейнера. Отладка в Kubernetes — это порядок, в котором ты читаешь эти три источника, чтобы за пару минут дойти от слова Pending или CrashLoopBackOff до конкретной причины. На работе это первый час любого инцидента, а на собеседовании вопрос «под не стартует, что будешь делать» проверяет, есть ли у тебя такой порядок или только список команд
🧭 Алгоритм: от статуса к причине
Статус пода показывает этап, на котором всё остановилось, а этап — куда смотреть дальше:
- Под не назначен на узел. Статус
Pending, вkubectl get pod -o wideколонка NODE пустая. Ответ в событииFailedScheduling - Узел назначен, контейнер не создан.
ContainerCreating,ErrImagePull,ImagePullBackOff,CreateContainerConfigError. Причина в событиях пода - Контейнер запускался и умер.
CrashLoopBackOff,OOMKilled,Error. Причина в логах прошлого запуска и в коде выхода - Контейнер работает, трафик не доходит. Статус
Running, но READY0/1или Service молчит. Смотришь пробы, EndpointSlice и порты
Первые три команды одинаковы для всех случаев:
kubectl get pod orders-7d9f-x2k -o wide # статус, рестарты, узел, IP
kubectl describe pod orders-7d9f-x2k # Last State, Exit Code, внизу Events
kubectl get events -n shop --sort-by=.lastTimestamp # события namespace по времениdescribe показывает события только этого пода, а события namespace нужны, когда виноват соседний объект: квота, PVC, узел в NotReady. События живут недолго, по умолчанию около часа: вчерашнее падение разбирают по логам и метрикам
🔎 Этапы по очереди
Pending: планировщик не нашёл узел
В событии FailedScheduling планировщик пишет, сколько узлов он проверил и почему отказал каждому: 0/5 nodes are available и дальше причины с числом узлов. Частые варианты:
Insufficient cpuилиInsufficient memory— сумма requests подов на узлах не оставила места. Планировщик смотрит на requests, а не на реальную загрузку: узел может быть загружен на 20% и всё равно «полным»had untolerated taint— на узлах taint, а у пода нет tolerationdidn't match Pod's node affinity/selector—nodeSelectorили affinity требует метку, которой нет ни на одном узлеpod has unbound immediate PersistentVolumeClaims— под ждёт PVC, который не привязан: нет подходящего PV или StorageClass не создал том
Бывает, что пода нет вовсе, а реплик меньше, чем в replicas: ReplicaSet упёрся в ResourceQuota и не создал под, причина в событиях ReplicaSet. Как планировщик выбирает узел, разобрано на странице «Планирование и масштабирование», привязка томов — на странице «Хранение данных»
ContainerCreating и CreateContainerConfigError
ContainerCreating дольше минуты почти всегда означает том или сеть. В событиях ищи:
FailedMount— не смонтировался том. Если в томе Secret или ConfigMap, которого нет, будетsecret "orders-tls" not foundFailedAttachVolumeсMulti-Attach error— диск с режимомReadWriteOnceещё подключён к старому узлу. Так бывает при выкатке Deployment с одним диском на другой узел. Для таких сервисов берут стратегиюRecreateили StatefulSetFailedCreatePodSandBox— CNI не выдал поду сеть, это вопрос к сетевому плагину узла
CreateContainerConfigError возникает, когда kubelet не может собрать конфигурацию контейнера. Чаще всего env ссылается на Secret или ключ, которого нет: secret "orders-secret" not found или couldn't find key DB_DSN. Обрати внимание на разницу: отсутствующий Secret в env даёт этот статус, а в томе — висящий ContainerCreating
ErrImagePull и ImagePullBackOff
ErrImagePull означает неудачную попытку, ImagePullBackOff — паузу перед следующей, и пауза растёт до 300 секунд. Текст в событиях подсказывает причину:
| Что в событии | Причина | Что делать |
|---|---|---|
not found, manifest unknown | Опечатка в имени или теге, образ не запушен, нет сборки под архитектуру узла | Сверить тег с реестром |
unauthorized, pull access denied | Приватный реестр без учётных данных | Secret kubernetes.io/dockerconfigjson и imagePullSecrets |
| Упоминание pull rate limit | Лимит Docker Hub | Логиниться, держать зеркало или прокси-кэш |
i/o timeout, no such host | Узел не видит реестр | DNS, прокси, фаервол узла |
imagePullSecrets работают только в namespace пода. Secret из default в shop не виден, его создают в каждом namespace или прописывают в ServiceAccount. У Docker Hub лимит для анонимных запросов — 100 скачиваний за 6 часов на IPv4-адрес или подсеть IPv6 /64
CrashLoopBackOff: читай код выхода
Kubelet перезапускает упавший контейнер с паузой 10, 20, 40 секунд и дальше, до потолка в 5 минут, а после 10 минут нормальной работы сбрасывает счётчик. В последних версиях потолок стал настраиваемым: с Kubernetes 1.35 в бете и включено по умолчанию поле crashLoopBackOff.maxContainerRestartPeriod в конфигурации kubelet, от 1 до 300 секунд на узел. В альфе с 1.33 есть ещё флаг ReduceDefaultCrashLoopBackOffDecay: старт с 1 секунды и потолок 60. В обычном кластере по-прежнему 5 минут
Логи текущего контейнера часто пусты, потому что он ещё ждёт своего запуска. Нужен прошлый:
kubectl logs orders-7d9f-x2k --previous # вывод упавшего запуска
kubectl logs orders-7d9f-x2k --all-containers # все контейнеры, включая init
kubectl get pod orders-7d9f-x2k \
-o jsonpath='{.status.containerStatuses[0].lastState.terminated}'Последняя команда отдаёт exitCode, reason, время старта и падения. По коду понятно, кто убил процесс:
| Код | Что это | Где искать причину |
|---|---|---|
0 | Процесс завершился сам, а restartPolicy: Always его поднимает | Команда отработала и вышла: скрипт вместо сервера, демон ушёл в фон |
1 | Ошибка приложения | Логи --previous: нет переменной, не та база, паника при старте |
137 | 128 плюс 9, SIGKILL | С Reason: OOMKilled — лимит памяти. Без него — kubelet добил процесс после terminationGracePeriodSeconds, например после проваленной liveness |
143 | 128 плюс 15, SIGTERM | Процесс умер от SIGTERM и не перехватил его. Если это не остановка пода, ищи, кто его остановил: liveness, выкатка, вытеснение |
137 не всегда OOM. OOM ставит Reason: OOMKilled в Last State. Если причина Error с кодом 137, процесс не уложился в период остановки и получил SIGKILL. Частая пара: liveness слишком строгая, kubelet останавливает медленный сервис, тот не успевает за 30 секунд. Как настраивать пробы и лимиты памяти, разобрано на странице «Пробы, ресурсы и деплой без простоя». Под, вытесненный с узла из-за нехватки памяти, выглядит иначе: фаза Failed и причина Evicted
Running, но не работает
READY 0/1 при статусе Running значит, что не проходит readiness. В событиях Readiness probe failed и ответ. При connection refused сервис слушает другой порт или 127.0.0.1, при коде 503 сам сервис считает себя неготовым
Если поды готовы, а Service не отвечает, проверь цепочку от Service к подам:
kubectl get endpointslices -l kubernetes.io/service-name=orders # есть ли адреса
kubectl get svc orders -o jsonpath='{.spec.selector}' # что выбирает Service
kubectl get pods -l app=orders --show-labels # совпадают ли метки
kubectl port-forward pod/orders-7d9f-x2k 8080:8080 # отвечает ли сам подПустой EndpointSlice — селектор не совпал с метками или поды не ready. Адреса есть, а соединение не проходит — targetPort не совпадает с портом, который слушает приложение, или трафик режет NetworkPolicy. port-forward ходит к поду в обход Service и kube-proxy: если так под отвечает, проблема между Service и подом. Старая команда kubectl get endpoints с 1.33 выдаёт предупреждение об устаревшем API, смотри EndpointSlice. DNS, kube-proxy и политики — на странице «Сети в Kubernetes»
🧰 Когда в контейнере нет shell
В distroless-образе нет sh, и kubectl exec упирается в executable file not found. Для этого есть эфемерный контейнер: kubectl debug добавляет в живой под временный контейнер со своим образом и утилитами
kubectl debug -it orders-7d9f-x2k --image=busybox:1.36 --target=orders--target подключает отладочный контейнер к pid namespace контейнера orders: ps покажет процесс сервиса, а его файловая система откроется через /proc/<pid>/root. Сеть у всех контейнеров пода и так общая, поэтому wget localhost:8080 пойдёт прямо в сервис. Эфемерный контейнер нельзя удалить из пода, он остаётся в спецификации до пересоздания пода, а права на него выдаются отдельно, через подресурс pods/ephemeralcontainers
Когда контейнер падает так быстро, что подключиться некуда, делают копию пода:
# копия с общим pid namespace и отладочным контейнером рядом
kubectl debug orders-7d9f-x2k -it --image=ubuntu --share-processes --copy-to=orders-debug
# копия, где контейнер вместо сервиса запускает shell
kubectl debug orders-7d9f-x2k -it --copy-to=orders-debug --container=orders -- sh
# копия с другим образом, например debug-сборкой
kubectl debug orders-7d9f-x2k --copy-to=orders-debug --set-image=orders=registry.example.com/orders:1.4.2-debugКопия не принадлежит ReplicaSet, после отладки её удаляют руками
Узел отлаживают так же: kubectl debug node/worker-3 -it --image=ubuntu запускает под в сетевом, pid и ipc namespace узла, а корень узла монтирует в /host. Так без SSH смотрят логи kubelet и crictl ps. Под без привилегий, и chroot /host может не сработать, тогда добавляют --profile=sysadmin. Профиль по умолчанию в актуальном kubectl — general
kubectl top pod и kubectl top node показывают текущее потребление CPU и памяти и работают только с установленным metrics-server. Без него команда сообщает, что Metrics API недоступен. Это снимок, историю перед OOM смотрят в Prometheus
📋 Шпаргалка: симптом → где смотреть → причина
| Симптом | Где смотреть | Частая причина |
|---|---|---|
Pending, узла нет | describe pod, событие FailedScheduling | Не хватает requests, taint, nodeSelector, PVC не привязан |
Подов меньше, чем replicas | get events, события ReplicaSet | ResourceQuota не дала создать под |
ContainerCreating | События FailedMount, FailedAttachVolume | Нет Secret для тома, Multi-Attach на ReadWriteOnce |
CreateContainerConfigError | describe pod | Нет Secret, ConfigMap или ключа в env |
ImagePullBackOff | События Failed у пода | Тег, нет imagePullSecrets, лимит Docker Hub |
CrashLoopBackOff | logs --previous, lastState.terminated | Ошибка конфигурации, нет зависимости, OOM, liveness |
OOMKilled, код 137 | describe pod, Last State | Лимит памяти ниже реального потребления |
Running, READY 0/1 | События Readiness probe failed | Не тот порт, сервис слушает 127.0.0.1, долгий прогрев |
| Service не отвечает | EndpointSlice, селектор, targetPort | Метки не совпали, порт контейнера другой, NetworkPolicy |
⚠️ Где ошибаются
Начинают с логов, когда контейнер ещё не запускался. При Pending и ImagePullBackOff логов нет и быть не может: процесс не стартовал. Сначала статус и события, логи — только когда контейнер уже работал
Поднимают лимит памяти на любой код 137. Без Reason: OOMKilled память ни при чём: процесс убили после проваленной пробы или долгой остановки
🎯 Вопросы с собеседований
Под не стартует. Расскажи, как будешь искать причину
Сначала kubectl get pod -o wide: статус и есть ли узел. Если Pending без узла, читаю FailedScheduling в describe: requests, taints, nodeSelector, PVC. Если узел есть, но контейнер не создан, смотрю события: образ не скачался, том не смонтировался, нет Secret. Если контейнер падает, беру logs --previous и код выхода из Last State. Код 1 означает ошибку приложения, 137 с OOMKilled говорит о памяти, а 137 без него или 143 — что процесс убили снаружи. Если под Running, но не ready, смотрю события readiness и порты. Исправляю манифест, а не под, и смотрю, что выкатка прошла
Под в Pending. Что проверишь?
Первое — событие FailedScheduling в kubectl describe pod: там видно, сколько узлов проверено и почему каждый отказал. Insufficient cpu или memory значит, что requests не помещаются. untolerated taint говорит о нехватке toleration, node affinity/selector об узле без нужной метки, unbound PersistentVolumeClaims о непривязанном PVC. Если пода нет вовсе, смотрю события ReplicaSet и квоты namespace
Что значит exit code 137? Чем он отличается от 143?
137 — это 128 плюс 9, процесс получил SIGKILL. Если в Last State Reason: OOMKilled, ядро убило его за превышение лимита памяти. Если причина Error, kubelet добил процесс после периода остановки, например не успел выключиться после проваленной liveness. 143 — 128 плюс 15, процесс умер от SIGTERM и не обработал сигнал. Код 1 — ошибка самого приложения, тут ответ в логах
Как отладить distroless-контейнер, где нет shell?
kubectl debug -it <pod> --image=busybox --target=<container> добавляет эфемерный контейнер с утилитами в тот же pid namespace. Сеть пода общая, так что можно ходить на localhost, а файлы сервиса видны через /proc/<pid>/root. Если контейнер падает сразу, делаю копию пода через --copy-to и меняю команду на sh или образ на debug-сборку
Поды Running, а сервис не отвечает. Где ищешь?
Смотрю kubectl get endpointslices -l kubernetes.io/service-name=<svc>. Пусто — селектор Service не совпал с метками подов или поды не прошли readiness. Адреса есть — проверяю, что targetPort совпадает с портом, который слушает приложение, и что оно слушает не 127.0.0.1. port-forward к поду в обход Service показывает, жив ли сам сервис. Если под отвечает, а через Service нет, проверяю NetworkPolicy и DNS
ImagePullBackOff. Какие бывают причины?
Опечатка в имени или теге и образ, который не запушили. Приватный реестр без imagePullSecrets, или Secret лежит в другом namespace. Лимит Docker Hub: анонимно 100 скачиваний за 6 часов на IP, и кластер за одним NAT быстро его выбирает. Узел не видит реестр из-за DNS или фаервола. Причина написана в событии пода, а после исправления kubelet может ждать следующей попытки до 5 минут, поэтому под проще удалить
📚 Что почитать
- Debug Running Pods — эфемерные контейнеры, копии пода, отладка узла и профили
kubectl debug - Debug Pods — что проверять у
Pending,Waitingи Service без адресов - Pod Lifecycle — фазы, состояния контейнеров и как устроена пауза перезапуска
- Images —
imagePullPolicy,imagePullSecretsи поведениеImagePullBackOff