{"id":178,"library":"kubernetes","title":"Official Kubernetes Python Client","description":"The official Python client library for Kubernetes provides a comprehensive and low-level API to interact with Kubernetes clusters. It allows programmatic management of Kubernetes resources, automating tasks typically performed via `kubectl`. Maintained by the Kubernetes community, it mirrors the full Kubernetes API surface. The current stable version is 35.0.0, with releases following the Kubernetes versioning scheme for major versions.","status":"active","version":"35.0.0","language":"en","source_language":"en","source_url":"https://github.com/kubernetes-client/python","tags":["kubernetes","k8s","client","orchestration","cloud-native","devops"],"install":[{"cmd":"pip install kubernetes","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"SSL certificate validation","package":"certifi","optional":false},{"reason":"Duration parsing utility","package":"durationpy","optional":false},{"reason":"Date and time utilities","package":"python-dateutil","optional":false},{"reason":"YAML parsing for kubeconfig","package":"pyyaml","optional":false},{"reason":"HTTP client library","package":"requests","optional":false},{"reason":"OAuth 1.0/2.0 support for requests","package":"requests-oauthlib","optional":false},{"reason":"Python 2/3 compatibility utilities","package":"six","optional":false},{"reason":"HTTP client connection pooling","package":"urllib3","optional":false},{"reason":"WebSocket protocol implementation","package":"websocket-client","optional":false},{"reason":"Azure Active Directory Authentication Library (optional for Azure Kubernetes Service integration)","package":"adal","optional":true},{"reason":"Google Authentication Library (optional for Google Kubernetes Engine integration)","package":"google-auth","optional":true}],"imports":[{"note":"Provides API client classes like CoreV1Api, AppsV1Api, etc. for interacting with Kubernetes resources.","symbol":"client","correct":"from kubernetes import client"},{"note":"Provides utilities for loading Kubernetes configuration (e.g., from kubeconfig file or in-cluster).","symbol":"config","correct":"from kubernetes import config"},{"note":"Provides Watch API for real-time monitoring of Kubernetes resources.","symbol":"watch","correct":"from kubernetes import watch"},{"note":"Used for handling streaming calls like pod exec or attach, especially for versions 4.0 and above.","symbol":"stream","correct":"from kubernetes import stream"}],"quickstart":{"code":"import os\nfrom kubernetes import client, config\n\n# Load Kubernetes configuration\n# Try to load in-cluster config first, then kubeconfig file\ntry:\n    config.load_incluster_config()\n    print(\"Loaded in-cluster Kubernetes config.\")\nexcept config.ConfigException:\n    try:\n        # Specify kubeconfig file path, defaults to ~/.kube/config\n        kubeconfig_path = os.environ.get('KUBECONFIG', os.path.expanduser('~/.kube/config'))\n        config.load_kube_config(config_file=kubeconfig_path)\n        print(f\"Loaded kubeconfig from {kubeconfig_path}.\")\n    except config.ConfigException:\n        print(\"Could not load Kubernetes config from in-cluster or kubeconfig file.\")\n        print(\"Ensure you are running inside a cluster or have a valid KUBECONFIG set.\")\n        exit(1)\n\nv1 = client.CoreV1Api()\nprint(\"Listing pods with their IPs:\")\n# Use watch=False for a single list operation\ntry:\n    ret = v1.list_pod_for_all_namespaces(watch=False)\n    for i in ret.items:\n        print(f\"{i.status.pod_ip}\\t{i.metadata.namespace}\\t{i.metadata.name}\")\nexcept client.ApiException as e:\n    print(f\"Error listing pods: {e}\")\n    print(\"Ensure your credentials have permissions to list pods.\")","lang":"python","description":"This quickstart demonstrates how to initialize the Kubernetes Python client by loading configuration (either in-cluster or from a kubeconfig file) and then listing all pods across all namespaces. It includes basic error handling for configuration loading and API calls, and is designed to be runnable in both cluster environments and local development setups with `KUBECONFIG` set."},"warnings":[{"fix":"For comprehensive, official documentation and active development, use `pip install kubernetes` (the package described here). If `kubernetes-client` 0.1.8 was intentionally sought, be aware of its limited documentation and potential maintenance status.","message":"The PyPI package `kubernetes-client` (version 0.1.8 as originally specified in the prompt) is a sparsely documented wrapper project that states it's 'based on the official kubernetes-client'. Most users searching for 'Kubernetes Python client' are looking for the official `kubernetes` package. This entry describes the official `kubernetes` package, not the `kubernetes-client` wrapper.","severity":"gotcha","affected_versions":"All versions of `kubernetes-client` (wrapper)"},{"fix":"Review the compatibility matrix in the official documentation/GitHub README to ensure your client version matches your Kubernetes cluster version for full feature compatibility.","message":"The versioning scheme for the official client changed starting with Kubernetes v1.17. Previously, client releases followed a different schema. Newer client versions (v17.x.x and above) align more closely with the Kubernetes minor and patch release numbers (vY.Z.P for Kubernetes v1.Y.Z).","severity":"breaking","affected_versions":"Client versions v12 and below, transitioning to v17+"},{"fix":"Consult the `CHANGELOG.md` on the official GitHub repository for detailed migration steps when upgrading major client versions. Update import paths for API classes and adjust object property access based on new naming conventions.","message":"Major breaking changes occurred related to the structure of API classes and property/parameter naming conventions in some releases (e.g., around OpenAPI generator updates). API classes might have moved, requiring import path updates (e.g., to `kubernetes.client.apis.tags.some_api`).","severity":"breaking","affected_versions":"Versions affected by OpenAPI generator updates (e.g., around `v1943` issue on GitHub). Typically between major client versions (e.g., 20.x.x to 21.x.x, or 25.x.x to 26.x.x)."},{"fix":"Use the `stream` module for `exec`, `attach`, and similar streaming calls. For example, instead of `resp = api.connect_get_namespaced_pod_exec(name, ...)`, use `resp = stream(api.connect_get_namespaced_pod_exec, name, ...)`. Refer to the `examples/exec.py` in the official repository.","message":"Directly calling `exec` or `attach` methods (e.g., `api.connect_get_namespaced_pod_exec`) is no longer supported for streaming operations from client version 4.0 onwards. These calls will fail or behave unexpectedly.","severity":"gotcha","affected_versions":"Client versions 4.0 and later"},{"fix":"Avoid using Alpha APIs in production environments. If absolutely necessary, pin your client version and thoroughly test upgrades. Monitor Kubernetes release notes for Alpha API stabilization or removal.","message":"Alpha APIs are unstable and can change significantly or disappear without prior notice in any release. Relying on them in production code carries a high risk of breaking changes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T09:43:48.790Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify network connectivity from where the client is running to the Kubernetes API server (e.g., `ping` or `telnet` to the API server IP/port). Ensure correct `KUBECONFIG` is loaded, or `load_incluster_config()` is used within a cluster. Check firewall rules.","cause":"Client cannot establish a connection to the Kubernetes API server, often due to network issues, incorrect API server address, or firewall blocking access.","error":"urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='****', port=6443): Max retries exceeded..."},{"fix":"Ensure your Kubernetes cluster's certificates are correctly configured for its hostname/IP. Alternatively, for development, you can disable SSL verification (`client.Configuration.verify_ssl = False`), but this is not recommended for production. Also, ensure `ipaddress` and `urllib3` are up to date and meet the client's `requirements.txt`.","cause":"Mismatch between the hostname in the SSL certificate presented by the API server and the hostname the client is trying to connect to. This can also be caused by outdated `ipaddress` or `urllib3` packages.","error":"ssl.CertificateError: hostname '****' doesn't match '****'"},{"fix":"Review and update Kubernetes RBAC policies. Create or modify `ClusterRole` and `ClusterRoleBinding` (or `Role` and `RoleBinding`) to grant the required permissions to the service account or user. Ensure `kubeconfig` context points to a user with sufficient privileges.","cause":"The service account or user credentials used by the client lack the necessary Role-Based Access Control (RBAC) permissions to perform the requested operation (e.g., list pods).","error":"kubernetes.client.rest.ApiException: (403)\nReason: Forbidden\nHTTP response body: {'kind': 'Status', 'apiVersion': 'v1', 'metadata': {}, 'status': 'Failure', 'message': 'pods is forbidden: User \"system:serviceaccount:default:default\" cannot list resource \"pods\" in API group \"\" in the namespace \"default\"'..."},{"fix":"Upgrade your `kubernetes` client library to a version compatible with `urllib3` 2.0.0+. Alternatively, downgrade `urllib3` to a version below 2.0.0 if you cannot update the Kubernetes client immediately, though upgrading the client is the recommended long-term solution.","cause":"Incompatibility with `urllib3` versions. Specifically, `urllib3` versions 2.0.0+ deprecated `getheaders()` and 2.6.0+ removed it, while older `kubernetes` client versions might still use it.","error":"AttributeError: 'HTTPResponse' object has no attribute 'getheaders'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.52,"mem_mb":43.6,"disk_size":"59.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.48,"mem_mb":43.7,"disk_size":"59.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":43.6,"disk_size":"60M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":43.7,"disk_size":"60M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.3,"mem_mb":49.1,"disk_size":"65.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.18,"mem_mb":49.1,"disk_size":"65.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.77,"mem_mb":49.1,"disk_size":"67M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.82,"mem_mb":49.1,"disk_size":"67M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":48.5,"disk_size":"56.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.76,"mem_mb":48.6,"disk_size":"56.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.72,"mem_mb":48.5,"disk_size":"58M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.73,"mem_mb":48.6,"disk_size":"58M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.69,"mem_mb":48.2,"disk_size":"55.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.65,"mem_mb":48.3,"disk_size":"55.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":48.2,"disk_size":"57M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.62,"mem_mb":48.2,"disk_size":"57M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":43.7,"disk_size":"58.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":43.6,"disk_size":"58.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.21,"mem_mb":43.7,"disk_size":"60M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.29,"mem_mb":43.6,"disk_size":"60M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}