{"id":7508,"library":"portforward","title":"Kubernetes Port-Forward","description":"The `portforward` library provides an easy-to-use Python interface for establishing port-forwarding connections to Kubernetes pods and services. It simplifies the underlying `kubernetes` client operations, allowing developers to programmatically manage forwarded ports. Currently at version 0.7.6, its release cadence is irregular, with updates typically occurring when new features or bug fixes are implemented, making it a stable choice for specific use cases.","status":"active","version":"0.7.6","language":"en","source_language":"en","source_url":"https://github.com/pytogo/portforward","tags":["kubernetes","port-forward","networking","devops","cloud"],"install":[{"cmd":"pip install portforward","lang":"bash","label":"Install portforward"}],"dependencies":[{"reason":"Required for interacting with Kubernetes clusters and performing port-forwarding operations.","package":"kubernetes","optional":false},{"reason":"Often used to interact with services exposed via port-forwarding; demonstrated in quickstart.","package":"requests","optional":true}],"imports":[{"symbol":"Portforward","correct":"from portforward import Portforward"}],"quickstart":{"code":"import os\nimport time\nimport requests\nfrom portforward import Portforward\nfrom kubernetes import config\n\n# --- Configuration for the quickstart example ---\n# Ensure you have a valid KubeConfig file (~/.kube/config) and a running Kubernetes cluster.\n# Replace 'nginx-pod' and 'default' with actual pod name and namespace in your cluster.\n# Set K8S_NAMESPACE, K8S_POD_NAME, K8S_POD_TARGET_PORT, K8S_LOCAL_PORT environment variables\n# or modify the defaults below to match your setup.\n\nnamespace = os.environ.get(\"K8S_NAMESPACE\", \"default\")\npod_name = os.environ.get(\"K8S_POD_NAME\", \"nginx-pod\") # Example: 'nginx-xxxxxx-xxxxx'\ntarget_port = int(os.environ.get(\"K8S_POD_TARGET_PORT\", \"80\"))\nlocal_port = int(os.environ.get(\"K8S_LOCAL_PORT\", \"8080\"))\n\nprint(f\"--- Kubernetes Port-Forward Quickstart ---\")\n\ntry:\n    # Load Kubernetes configuration\n    config.load_kube_config()\n    print(f\"Attempting to forward port {target_port} from pod '{pod_name}' in namespace '{namespace}' to local port {local_port}...\")\n\n    # Establish the port-forward connection using a context manager\n    with Portforward.from_pod(\n        namespace=namespace,\n        pod_name=pod_name,\n        target_port=target_port,\n        local_port=local_port\n    ) as pf:\n        print(f\"Successfully established port-forward: http://localhost:{pf.local_port}\")\n        print(\"You can now access your pod/service via this local address.\")\n\n        # Example: Make a request to the forwarded port\n        print(\"\\nAttempting a sample HTTP GET request via the forwarded port...\")\n        try:\n            # This will only succeed if the pod exposes an HTTP service on the target_port\n            response = requests.get(f\"http://localhost:{pf.local_port}\", timeout=5)\n            print(f\"Request successful! Status code: {response.status_code}\")\n            print(f\"Response (first 100 chars): {response.text[:100]}...\")\n        except requests.exceptions.ConnectionError:\n            print(\"Could not connect to the forwarded port. Is the target service running and exposing HTTP?\")\n            print(\"Please ensure the pod name, namespace, and target port are correct.\")\n        except Exception as e:\n            print(f\"An unexpected error occurred during the sample request: {e}\")\n\n        print(\"\\nKeeping port-forward active for 15 seconds. Press Ctrl+C to stop sooner.\")\n        time.sleep(15) # Keep the port forward open for a duration\n        print(\"Port-forward session ending.\")\nexcept config.ConfigException as e:\n    print(f\"Error loading Kubernetes configuration: {e}\")\n    print(\"Please ensure your KubeConfig file is valid and accessible (e.g., at ~/.kube/config) or your environment is configured for in-cluster access.\")\nexcept Exception as e:\n    print(f\"Failed to establish port-forward: {e}\")\n    print(\"Common causes: pod not found, incorrect namespace/pod_name, target_port not exposed, RBAC issues, or local port already in use.\")\n","lang":"python","description":"This quickstart demonstrates how to establish a port-forward to a Kubernetes pod and then make a simple HTTP request through the forwarded port. It handles common configuration loading for Kubernetes and provides error handling for typical issues. Ensure your `KUBECONFIG` is set up correctly and replace placeholder values for `namespace`, `pod_name`, `target_port`, and `local_port` with your actual Kubernetes resource details or set them via environment variables."},"warnings":[{"fix":"Ensure your `kubeconfig` file is valid, accessible, and correctly pointed to (e.g., via `KUBECONFIG` environment variable or `KUBERNETES_MASTER` for direct API server access). Verify your current context is correct.","message":"Kubernetes configuration issues are a common pitfall. The `portforward` library relies on the `kubernetes` client library's ability to load configuration (e.g., from `~/.kube/config`).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the Kubernetes user or service account executing the Python script has `port-forward` permission on the target pod/namespace. This usually involves `verbs: [\"get\", \"list\", \"watch\", \"create\", \"portforward\"]` on `pods/portforward` resources.","message":"Insufficient Kubernetes RBAC permissions can prevent port-forwarding. The user or service account needs specific permissions to 'portforward' on pods.","severity":"gotcha","affected_versions":"All"},{"fix":"Double-check that the `target_port` you specify corresponds to an open port on the target pod or service that is actively listening for connections. Verify this by using `kubectl get pod <pod-name> -o yaml` to check exposed ports or `kubectl exec <pod-name> -- netstat -tuln` (if netstat is available).","message":"The `portforward` library establishes the connection but does not validate if the specified target port inside the pod/service is actually open or serving traffic. Connecting to a non-existent internal port will result in connection issues on the local side.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your `~/.kube/config` file exists and is valid. Alternatively, set the `KUBECONFIG` environment variable to point to your kubeconfig file, or ensure your application is running within a Kubernetes cluster (in-cluster configuration).","cause":"The Kubernetes client library could not find or load a valid kubeconfig file.","error":"kubernetes.config.config_exception.ConfigException: Invalid kube-config file. No configuration found."},{"fix":"Verify the `pod_name` and `namespace` parameters are correct. Use `kubectl get pods -n <namespace>` to list available pods and confirm the exact name and namespace.","cause":"The specified pod name or namespace does not exist in the cluster or is misspelled.","error":"Failed to establish port-forward: Reason: b'Error forwarding port 80 to pod/my-app-pod - cause: pod \"my-app-pod\" not found'"},{"fix":"Choose a different `local_port` that is not currently in use. You can often find free ports above 1024. On Linux/macOS, `lsof -i :<port>` can show which process is using a port.","cause":"The `local_port` you are trying to use for the port-forward is already occupied by another process on your local machine.","error":"OSError: [Errno 48] Address already in use"}]}