Kubernetes Port-Forward

Overview

Establish port-forward connections to cluster services. Handles service discovery, credentials retrieval, connectivity verification, and cleanup. Supports RabbitMQ, PostgreSQL, and internal APIs.

Service Registry

Quick reference for the most common services. For the full inventory (all adapters, gestor documental, etc.), see [references/services.md](references/services.md).

Process

1. Find the service

# If you don't know the exact service name
kubectl --context=<env> get svc -n <namespace> | grep <keyword>

# For pods (when you need to forward to a specific pod)
kubectl --context=<env> get pods -n <namespace> | grep <keyword>

2. Start port-forward

# To a service (preferred — survives pod restarts)
kubectl --context=<env> port-forward -n <namespace> svc/<service> <local>:<remote>

# To a specific pod
kubectl --context=<env> port-forward -n <namespace> <pod-name> <local>:<remote>

Run in background so the terminal stays available. When running multiple port-forwards, use different local ports to avoid conflicts.

3. Verify connectivity

Use the service-specific verification command from the registry above.

4. Cleanup

# Kill port-forward on a specific port
kill $(lsof -ti:<local-port>) 2>/dev/null

# Kill all port-forwards
pkill -f "kubectl.*port-forward" 2>/dev/null

Credentials

Never hardcode credentials in skills or commands.

Retrieval order:

1. Ask the user if they know the credentials
2. Try Kubernetes secrets:

# RabbitMQ - check definitions for username
kubectl --context=<env> get secret rabbitmq-definitions-secret -n shared-infra \
  -o jsonpath='{.data.load_definition\.json}' | base64 -d | \
  python3 -c "import sys,json; [print(u['name']) for u in json.load(sys.stdin).get('users',[])]"

# RabbitMQ - PROD password
kubectl --context=prod get secret rabbitmq -n shared-infra \
  -o jsonpath='{.data.rabbitmq-password}' | base64 -d

# RabbitMQ - DEV password
kubectl --context=dev get secret dev-test-afianza-rabbit-ha-secret \
  -n shared-infra -o jsonpath='{.data.rabbitmq-password}' | base64 -d

# PostgreSQL - read from app pod config
kubectl --context=<env> exec -n plataformadato <app-pod> -- \
  cat /app/dist/src/config/production.config.js | grep -A5 postgresql

1. If secrets don't match, ask the user

Port Conflict Resolution

# Check what's using a port
lsof -i:<port>

# Use an alternative local port
kubectl --context=<env> port-forward -n <namespace> svc/<service> <alt-local>:<remote>

Common Mistakes