{"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.","language":"python","status":"active","last_verified":"Sun May 17","install":{"commands":["pip install portforward"],"cli":null},"imports":["from portforward import Portforward"],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-17","installed_version":"0.7.6","pypi_latest":"0.7.6","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":2.1,"avg_import_s":null,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"29.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"30M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"31.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"32M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"23.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"24M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"23.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":2,"import_time_s":null,"mem_mb":null,"disk_size":"24M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"29.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"portforward","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.1,"import_time_s":null,"mem_mb":null,"disk_size":"30M"}]}}