kubectl port-forward: Проброс порта из кластера на локальную машину

Базовый синтаксис

Команда kubectl port-forward создает туннель от вашей локальной машины к ресурсу в кластере. Это основной способ для отладки и прямого доступа к внутренним сервисам, не настраивая Ingress или LoadBalancer.

Самый простой пример — проброс порта к поду:

kubectl port-forward pod/my-postgres-pod 5432:5432

Разберем команду:

pod/my-postgres-pod — тип ресурса и его имя.
5432:5432 — пара портов локальный_порт:порт_в_поде. Команда заставляет локальный порт 5432 “слушать” подключения и перенаправлять их на порт 5432 внутри указанного пода. Теперь вы можете подключиться к БД как к localhost:5432.

Полезные флаги

--namespace — обязателен при работе с ресурсами не в default неймспейсе.

kubectl port-forward -n monitoring svc/grafana 3000:3000

Пример выше открывает доступ к Grafana из неймспейса monitoring на локальный порт 3000.

--address — по умолчанию проброс слушает только localhost. Чтобы разрешить подключения с других машин в сети, укажите 0.0.0.0.

kubectl port-forward --address 0.0.0.0 pod/my-app 8080:80

Теперь к вашему приложению можно обратиться по ваш_ip:8080 с любой машины в локальной сети.

Типичные сценарии

Отладка StatefulSet (например, Kafka или Cassandra). Часто нужно проверить работу конкретной ноды, подключившись к её внутреннему API. Найти под нужной ноды можно через селектор.

kubectl get pod -l app=cassandra,statefulset.kubernetes.io/pod-name=cassandra-2
kubectl port-forward cassandra-2 9042:9042

Теперь cqlsh localhost 9042 подключится именно к cassandra-2.

Доступ к внутреннему инструменту мониторинга. Многие Helm-чарты (например, для Redis или PostgreSQL) устанавливают вместе с основным приложением веб-интерфейс, который не выносится наружу. Проброс через сервис — самый быстрый способ его посмотреть.

kubectl port-forward svc/my-redis-master 9121:9121

После этого метрики Redis в формате Prometheus будут доступны по localhost:9121/metrics.

Частые ошибки

Неправильный выбор пода. Если указать просто имя пода, который пересоздается (например, Deployment), при его рестарте проброс разорвется и не восстановится автоматически. Для отладки таких workload надежнее пробрасывать порт через Service (svc/имя_сервиса), так как подключение будет сохраняться при смене подов.

Порт уже используется. Ошибка Unable to listen on port: listen tcp4 :5432: bind: address already in use. Проверьте, не запущен ли у вас локально PostgreSQL или другой сервис на этом порту. Либо освободите порт, либо пробрасывайте на другой локальный порт (например, 5433:5432).