Отладка Kubernetes: kubectl port-forward

Иллюстрация с логотипом Kubernetes

TL;DR

kubectl port-forward позволяет безопасно перенаправлять локальные порты на порты Pod внутри кластера Kubernetes. Это удобно для отладки баз данных, инструментов мониторинга и внутренних сервисов без создания публичных Service/Ingress. Используйте порт-форвардинг для временного доступа, соблюдайте политику безопасности и закрывайте сессию по окончании.

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

How Port Forwarding Works
Deploying a Sample Application
Using Kubectl to Port Forward to Kubernetes
Summary

Что такое порт-форвардинг и как это работает

Порт-форвардинг — это правило переадресации сетевых соединений (аналог NAT), которое перенаправляет трафик с локального порта на порт внутри кластера. Когда вы запускаете kubectl port-forward, локальные подключения к указанному порту на localhost перенаправляются в целевой Pod.

Ключевые моменты:

Перенаправление происходит на уровне TCP-портов. UDP пока не поддерживается.
Вы указываете пару local:remote (например, 33060:3306) — локальный порт и порт внутри Pod.
По умолчанию kubectl слушает 127.0.0.1 и ::1, то есть доступ ограничен машиной, где вы запустили команду.

Термин в одну строку: kubectl port-forward создаёт зашифрованный туннель между вашим localhost и портом внутри Pod через API-сервер Kubernetes.

Когда имеет смысл использовать порт-форвардинг

Быстрая отладка базы данных или сервиса, который не должен быть публичным.
Доступ к внутренним административным интерфейсам (Prometheus, Grafana, pgAdmin и т. п.).
Одноразовая диагностика инцидента без изменения конфигурации кластера.

Важно: порт-форвардинг — временное средство. Для постоянного доступа используйте сервисы с контролем доступа и сетевыми политиками.

Развёртывание примерного приложения (пример на MySQL)

Ниже — минимальный пример Deployment с MySQL, который мы используем для демонстрации port-forward. Перед использованием в проде замените простой пароль на безопасный.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - image: mysql:8.0
        name: mysql
        env:
        - name: MYSQL_ROOT_PASSWORD
          value: mysql

Сохраните файл как mysql.yaml и примените:

$ kubectl apply -f mysql.yaml

Ожидаемый вывод:

deployment.apps/mysql created

Проверьте Pods:

$ kubectl get pods

Пример вывода (формат строки оставлен для наглядности):

NAME READY STATUS RESTARTS AGE
mysql-5f54dd5789-t5fzc 1/1 Running 0 2s

Примечание: имена Pod и метаданные зависят от контроллеров и версий образов.

Как использовать kubectl port-forward

Запустите перенаправление портов, указав целевой объект (pod, deployment, svc поддерживается) и биндинг портов:

$ kubectl port-forward deployment/mysql 33060:3306

Ожидаемые сообщения:

Forwarding from 127.0.0.1:33060 -> 3306
Forwarding from [::1]:33060 -> 3306

После этого вы можете подключиться локально, например, с помощью mysql-клиента:

$ mysql --host 127.0.0.1 --port 33060 -u root -p

Держите окно терминала, где запущен kubectl port-forward, открытым: при закрытии соединения или нажатии Ctrl+C туннель прекращается.

Синтаксис портов: local:remote

33060:3306 — локальный порт 33060 проброшен на 3306 в Pod.
Указав только один порт 3306, kubectl считает его и локальным, и удалённым:

$ kubectl port-forward deployment/mysql 3306

Можно позволить kubectl выбрать свободный локальный порт, оставив левую часть пустой:

$ kubectl port-forward deployment/mysql :3306

Вывод покажет автоматически выбранный порт, например 34923.

Адреса прослушивания

По умолчанию kubectl слушает только на:

IPv4: 127.0.0.1
IPv6: ::1

Чтобы прослушивать дополнительные адреса, используйте флаг –address:

$ kubectl port-forward deployment/mysql :3306 --address 127.0.0.1,192.168.0.1

Флаг принимает IP-адреса и ключевое слово localhost, которое эквивалентно 127.0.0.1 и ::1.

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

Когда порт-форвардинг не подходит (контраргументы)

Требуется постоянный публичный доступ к сервису — лучше использовать Service типа LoadBalancer/Ingress.
Нужна балансировка нагрузки между несколькими экземплярами — port-forward привязан к конкретному Pod/объекту и не обеспечивает балансировку.
UDP-трафик — kubectl port-forward поддерживает только TCP.
Высоконагруженные соединения в продакшене — туннель через kubectl не предназначен для высокопроизводительной, постоянной маршрутизации трафика.

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

Service с типом NodePort или LoadBalancer — для постоянного доступа (с учётом безопасности).
Ingress контроллер — HTTP/HTTPS маршрутизация и сертификаты.
kubectl proxy — прокси к API-серверу (для API-запросов), не для произвольных TCP-портов.
SSH-туннелирование от jump-хоста к машине, где доступен kubectl — для удалённого безопасного доступа.
Port-forward как systemd-сервис (для автоматизации в дев окружении), но с осторожностью.

Руководство по устранению неполадок (runbook)

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

$ kubectl get pods -l app=mysql -o wide

Убедитесь, что объект (deployment/pod/service) существует и есть Ready контейнеры.
Попробуйте порт-форвард к конкретному Pod:

$ kubectl port-forward pod/mysql-5f54dd5789-t5fzc 33060:3306

Если порт занят локально, выберите другой локальный порт или найдите процесс:

Linux/macOS: lsof -i :33060 / ss -ltnp | grep 33060

Проверьте RBAC: пользователь/контекст, от которого вы запускаете kubectl, должен иметь права на pods/portforward.
Если соединение закрывается сразу — посмотрите логи kubectl и kube-apiserver на предмет ошибок авторизации или сетевых проблем.
Для проблем с именами хостов и IPv6 попробуйте явно указать 127.0.0.1 как host в клиенте.

Критические команды для диагностики:

$ kubectl describe pod 
$ kubectl logs 
$ kubectl auth can-i create pods/portforward --namespace=

Контрольные списки по ролям

Разработчик:

Убедиться, что Pod запущен и Ready
Использовать port-forward только локально
Закрыть туннель после отладки

SRE/Операции:

Проверить RBAC политики и аудит доступа
Документировать временные порт-форварды при инцидентах
Настроить ограниченные jump-хосты для удалённого администрирования

Команда безопасности:

Убедиться, что логируется использование port-forward
Запретить открытие на 0.0.0.0 без одобрения

Безопасность и соответствие

Порт-форвардинг прокидывает трафик через ваш текущий kubeconfig-контекст. Права и ограничения зависят от привилегий пользователя.
Лучше всего запускать port-forward с минимально необходимыми правами и на localhost.
Для удалённого доступа используйте SSH-туннелирование к безопасному jump-хосту вместо открытого прослушивания на всех интерфейсах.
Если данные чувствительны, убедитесь, что клиентское соединение использует шифрование (например, TLS в приложении) поверх TCP.
Для соответствия (GDPR и т. п.) логируйте кто, когда и зачем открывал туннель к критичным сервисам.

Шпаргалка: команды и шаблоны

Port-forward к Deployment:

kubectl port-forward deployment/ :

Port-forward к Pod:

kubectl port-forward pod/ :

Автоматический локальный порт (левую часть оставляем пустой):

kubectl port-forward deployment/mysql :3306

Прослушивание нескольких адресов:

kubectl port-forward deployment/mysql 33060:3306 --address 127.0.0.1,192.168.0.1

Методика: шаги для безопасной отладки с помощью port-forward

Подтвердите, что pod работает и готов.
Выберите локальный порт, который не конфликтует с другими сервисами.
Запустите port-forward на localhost.
Подключитесь локальным клиентом к указанному локальному порту.
Соберите диагностические данные и завершите сессию.
Если нужно — зафиксируйте действия и логи для аудита.

Модель принятия решения (Mermaid)

flowchart TD
  A[Нужно получить доступ к сервису в кластере?] --> B{Требуется постоянный доступ?}
  B -- Да --> C[Использовать Service/Ingress с аутентификацией]
  B -- Нет --> D{Требуется балансировка/высокая нагрузка?}
  D -- Да --> C
  D -- Нет --> E[Использовать kubectl port-forward]
  E --> F[Ограничить адреса '--address' и логировать доступ]

Совместимость и ограничения

Работает только с TCP.
Поддерживает объекты типа pod, deployment, service.
Зависит от версии kubectl и kube-apiserver; лучше использовать сопоставимые версии клиента и сервера.
RBAC может блокировать операцию, если права не предоставлены.

Примеры отказов и как их избежать

Проблема: порт занят локально — решение: подобрать свободный порт или завершить локальный процесс.
Проблема: отсутствие прав — решение: проверить политики RBAC и запросить minimum required права (pods/portforward).
Проблема: туннель часто рвётся — решение: проверить стабильность сети до API-сервера и посмотреть логи kubectl.

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

Подключение к целевому сервису по локальному порту успешно выполняется.
Доступ ограничен только тем пользователям, которым это разрешено.
После завершения отладки соединение разрывается.

Резюме

kubectl port-forward — простой, безопасный и быстрый способ доступа к приватным сервисам в Kubernetes для отладки и диагностики. Используйте его для временных задач, следуя политике безопасности и аудита. Для постоянного и публичного доступа применяйте более устойчивые и контролируемые механизмы (Service, Ingress, VPN).

Важное замечание: порт-форвардинг делает сервис доступным только через тот узел, где запущен kubectl, и опирается на права, описанные в kubeconfig/RBAC.