kubectl debug: отладка Pod с эфемерными контейнерами

Логотип Kubernetes

Коротко: команда kubectl debug добавляет в Pod временный (эфемерный) контейнер, где можно запускать привычные инструменты для поиска причин проблем без изменения работающих контейнеров. Подходит для интерактивной диагностики, копирования Pod с включённым шарингом процессов и выполнения одноразовых команд. Важно: эфемерные контейнеры не персистентны и имеют ограничения (нет проб, привязок портов, авто‑рестартов).

Quick Links

Preparing to Use Kubectl Debug
Using Kubectl Debug
Copying Pods
Optional Arguments
Conclusion

Введение

Диагностика проблем в запущенных workload’ах Kubernetes иногда сводится к простому чтению логов через

kubectl logs

Однако часто требуется живое подключение к окружению Pod, чтобы просмотреть процессы, состояние файловой системы или выполнить отладочные утилиты. Команда kubectl debug упрощает такие задачи: она добавляет в существующий Pod новый краткоживущий контейнер — эфемерный контейнер — с инструментами, которых нет в основном образе приложения.

Определение: эфемерный контейнер — временный контейнер, присоединяемый к уже существующему Pod для диагностических целей.

Зачем использовать эфемерные контейнеры?

Не мутировать реальный контейнер. Установка отладочных утилит внутрь работающего контейнера изменит его состояние.
Быстро получить среду с нужными утилитами (strace, ss, tcpdump, nano, curl и т. п.).
Безопасно исследовать процессы и файловую систему через копию Pod.

Важно: эфемерные контейнеры по дизайну временные. У них нет проб (liveness/readiness), они не привязывают порты и не перезапускаются автоматически.

Подготовка к использованию kubectl debug

kubectl debug был добавлен в Kubectl и Kubernetes начиная с версии 1.18 как клиентская команда и опирается на возможность создания эфемерных контейнеров. Функция эфемерных контейнеров вышла в бета в Kubernetes v1.23 и включена по умолчанию. Если ваш кластер старше, потребуется вручную включить соответствующий FeatureGate.

Проверка совместимости:

kubectl version --client && kubectl get nodes

Если у вас устаревший API-сервер, обратитесь к администратору кластера или обновите кластер.

Примечание: большинство образов приложений минималистичны и не содержат инструментов отладки. Эфемерный контейнер позволяет использовать более тяжелый образ только для диагностики.

Использование kubectl debug — базовый пример

Создаём тестовый деплоймент:

$ kubectl create deployment nginx --image=nginx:latest

deployment.apps/nginx created

Получаем список Pod:

$ kubectl get pods

NAME READY STATUS RESTARTS AGE

nginx-55649fd747-qsnr2 1/1 Running 0 5s

В нашем примере Pod называется nginx-55649fd747-qsnr2.

Запускаем эфемерный контейнер с образом Ubuntu и подключаемся к интерактивной оболочке:

$ kubectl debug -it --image=ubuntu:20.04 nginx-55649fd747-qsnr2

Флаги:

-it эквивалентны --stdin --tty — выделяют TTY и подключают stdin для интерактивной сессии.
--image — образ для эфемерного контейнера.
неназванный аргумент — имя Pod, к которому присоединяемся.

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

Копирование Pod и шаринг пространств имён процессов

Команда kubectl debug поддерживает --copy-to, создавая копию целевого Pod и добавляя в неё эфемерный контейнер. Исходный Pod остаётся нетронутым.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug nginx-55649fd747-qsnr2

Это безопаснее для production: вы не рискуете менять работающий Pod.

Чтобы увидеть процессы оригинального контейнера из эфемерного, используйте шаринг namespace процессов через флаг --share-processes при копировании:

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --share-processes nginx-55649fd747-qsnr2

Внутри эфемерного контейнера вы увидите процессы NGINX:

$ ps ax

PID USER TIME COMMAND

1 root 0:00 /pause

9 root 0:00 nginx: master process nginx -g daemon off;

Процессы остаются в контейнере NGINX, но благодаря шарингу они видимы из эфемерного контейнера. Также доступна файловая система оригинального контейнера через /proc//root:

$ ls /proc/9/root/etc/nginx

conf.d fastcgi_params mime.types modules nginx.conf …

Это делает копирование Pod мощным инструментом для инспекции процессов и файлов без вмешательства в работающий контейнер.

Неинтерактивные сценарии и –attach

Эфемерный контейнер не обязан быть интерактивным. Можно выполнять одноразовые команды в стиле kubectl exec и контролировать подключение вывода по --attach:

$ kubectl debug --image=ubuntu:20.04 --copy-to nginx-debug --share-processes --attach true nginx-55649fd747-qsnr2 -- ls /proc/9/root/etc/nginx

Вы получите вывод и команда завершится.

Опциональные аргументы и поведение

--copy-to — создаёт копию Pod и добавляет в неё эфемерный контейнер. Исходный Pod не удаляется.
--replace — при использовании с --copy-to заменяет исходный Pod на копию (старый Pod будет остановлен).

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --replace nginx-55649fd747-qsnr2

--same-node — заставляет копию запускаться на том же Node, что и оригинал. Полезно для воспроизводимости, если в кластере есть различия между нодами.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --same-node nginx-55649fd747-qsnr2

--env — добавляет переменные окружения в эфемерный контейнер. Удобно для настройки отладочных утилит.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --env EDITOR=/usr/bin/nano nginx-55649fd747-qsnr2

--attach — контролирует, будет ли к контейнеру подключён stdout/stderr при запуске неинтерактивной команды.

Когда kubectl debug не подходит

Если требуется профилирование с долгим хранением данных. Эфемерный контейнер временный; логи и артефакты, созданные в нём, могут исчезнуть.
Для изменения конфигурации сервисов — используйте корректные CI/CD‑процессы и обновление образов.
Если у Pod включён строгий SecurityContext с запрещёнными возможностями, некоторые инструменты могут работать некорректно.

Контрпример: попытка воспроизвести проблему, зависящую от длительной нагрузки или состояния, сохраняемого между перезапусками, лучше делать через тестовую среду или staging.

Альтернативные подходы

kubectl exec — быстрые действия внутри текущего контейнера, если в образ встроены нужные утилиты.
Sidecar-отладочные контейнеры в манифесте — полезны если нужно длительное присутствие инструментов рядом с приложением.
Дамп состояния приложений в miejsca хранения (S3, PV) — для ретроспективного анализа.
Использование сторонних отладочных инструментов: kubelet debug handlers, runtime tools (CRI‑specific).

Пошаговая методология (мини‑методология)

Соберите минимальную информацию: логи, метрики, события (kubectl logs, kubectl describe pod).
Оцените риск влияния на production. Если риск высокий — используйте –copy-to.
Запустите эфемерный контейнер с образом, который содержит нужные утилиты.
Если нужно увидеть процессы — используйте –share-processes.
Соберите вывод команд и метаданные (ps, netstat/ss, strace, lsof, ls /proc/…).
Сделайте снимки конфигурации (kubectl get pod -o yaml) и при необходимости сохраните артефакты в постоянное хранилище.
Корректируйте гипотезы и итеративно повторяйте процесс.

Чек‑лист по ролям

Для разработчика (Dev):

Подготовить входные данные и воспроизводимый сценарий.
Указать образ с отладочными утилитами.
Проверить одинарные команды через –attach.

Для оператора (Ops/SRE):

Проверить версии Kubernetes и включённые FeatureGate.
Использовать –copy-to в production.
Собрать артефакты и удалить копию после диагностики.

Для инженера безопасности:

Оценить права, назначенные эфемерному контейнеру.
Проверить, не раскрываются ли секреты при копировании Pod.
Убедиться, что временные данные удалены.

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

Диагностика выполнена без внесения изменений в рабочий контейнер.
Все собранные артефакты сохранены в согласованном хранилище.
Копии Pod удалены после завершения работ (если использовались).
Неуспешные команды документированы, восстановление проведено.

Матрица рисков и смягчения

Утечка секретов при доступе к файловой системе — ограничить права, использовать временные сервис‑аккаунты.
Непреднамеренное влияние на производительность Node при запуске тяжёлого образа — использовать –same-node осторожно и следить за ресурсами.
Неправильная интерпретация процессов — всегда проверяйте PID и путь в /proc//root.

1‑строчный глоссарий

Pod — минимальная единица деплоймента в Kubernetes.
Эфемерный контейнер — временный контейнер для диагностики.
–copy-to — флаг, создающий копию Pod с добавленным контейнером.
–share-processes — включает шаринг пространства процессов между контейнерами Pod.

Совместимость и заметки по версиям

kubectl debug: доступен с v1.18 как клиентская команда.
Эфемерные контейнеры: бета с v1.23 и включены по умолчанию. На кластерах старше v1.23 требуется ручная активация.
Функционал зависит от CRI (runtime). В редких случаях поведение может отличаться между containerd и dockerd.

Совет: всегда проверяйте документацию вашей версии Kubernetes и runtime перед применением в production.

Шаблон команд и часто используемые сниппеты

Интерактивная сессия в существующем Pod:

kubectl debug -it --image=ubuntu:20.04

Скопировать Pod и подключить шаринг процессов:

kubectl debug -it --image=ubuntu:20.04 --copy-to  --share-processes

Копия на той же ноде:

kubectl debug -it --image=ubuntu:20.04 --copy-to  --same-node

Одноразовая команда с выводом:

kubectl debug --image=ubuntu:20.04 --copy-to  --share-processes --attach true  --

Примеры ошибок и как их диагностировать

Симптом: в копии при шаринге вы не видите нужный процесс.

Проверки:

Убедитесь, что PID совпадает: сравните ps ax в копии и kubectl exec в оригинальном контейнере.
Проверьте, не завершился ли процесс к моменту диагностики.
Проверьте SecurityContext оригинального контейнера — возможно, процессы изолированы.

Симптом: нет доступа к файлам через /proc//root.

Проверки:

Проверьте права доступа и монтирование томов.
Убедитесь, что process namespace действительно шарится (spec.shareProcessNamespace: true на копии).

Заключение

Эфемерные контейнеры и команда kubectl debug дают гибкие и безопасные варианты для интерактивной диагностики Kubernetes‑нагрузок. Они полезны, когда:

нужно быстро получить готовое окружение с инструментами отладки;
важно не менять работающие контейнеры;
требуется проанализировать процессы и файловую систему целевого контейнера через копию Pod.

Используйте –copy-to и –share-processes для безопасного и удобного анализа, а также применяйте чек‑листы и критерии приёмки, чтобы минимизировать операционные и безопасность риски.

Важно

После диагностики не забывайте удалять временные копии Pod и очищать артефакты.

Примечание

Перед использованием в production уточните версию Kubernetes и политику безопасности вашей организации.