К содержимому
Войти

DevOps Road Map

🔧 Отладка в Kubernetes

Сломанный под почти всегда сам говорит, что с ним не так: в статусе, в событиях и в коде выхода прошлого контейнера. Отладка в Kubernetes — это порядок, в котором ты читаешь эти три источника, чтобы за пару минут дойти от слова Pending или CrashLoopBackOff до конкретной причины. На работе это первый час любого инцидента, а на собеседовании вопрос «под не стартует, что будешь делать» проверяет, есть ли у тебя такой порядок или только список команд

🧭 Алгоритм: от статуса к причине

Статус пода показывает этап, на котором всё остановилось, а этап — куда смотреть дальше:

  1. Под не назначен на узел. Статус Pending, в kubectl get pod -o wide колонка NODE пустая. Ответ в событии FailedScheduling
  2. Узел назначен, контейнер не создан. ContainerCreating, ErrImagePull, ImagePullBackOff, CreateContainerConfigError. Причина в событиях пода
  3. Контейнер запускался и умер. CrashLoopBackOff, OOMKilled, Error. Причина в логах прошлого запуска и в коде выхода
  4. Контейнер работает, трафик не доходит. Статус Running, но READY 0/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, а у пода нет toleration
  • didn'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 found
  • FailedAttachVolume с Multi-Attach error — диск с режимом ReadWriteOnce ещё подключён к старому узлу. Так бывает при выкатке Deployment с одним диском на другой узел. Для таких сервисов берут стратегию Recreate или StatefulSet
  • FailedCreatePodSandBox — 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: нет переменной, не та база, паника при старте
137128 плюс 9, SIGKILLС Reason: OOMKilled — лимит памяти. Без него — kubelet добил процесс после terminationGracePeriodSeconds, например после проваленной liveness
143128 плюс 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 не привязан
Подов меньше, чем replicasget events, события ReplicaSetResourceQuota не дала создать под
ContainerCreatingСобытия FailedMount, FailedAttachVolumeНет Secret для тома, Multi-Attach на ReadWriteOnce
CreateContainerConfigErrordescribe podНет Secret, ConfigMap или ключа в env
ImagePullBackOffСобытия Failed у подаТег, нет imagePullSecrets, лимит Docker Hub
CrashLoopBackOfflogs --previous, lastState.terminatedОшибка конфигурации, нет зависимости, OOM, liveness
OOMKilled, код 137describe 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