kubernetes

The kubernetes PyPI package is the official Python client library for the Kubernetes API, maintained under the kubernetes-client organization alongside sibling clients for Go, Java, and other languages. Like those siblings, its API surface (kubernetes/client/) is largely generated from the Kubernetes OpenAPI/Swagger specification, giving full coverage of every core and extension API resource with typed models rather than hand-maintained bindings that lag the API.

Beyond the generated REST client, the package includes hand-written convenience layers: kubernetes.config for loading kubeconfig files or in-cluster service-account credentials, kubernetes.watch for streaming resource-change events, kubernetes.stream for exec/attach/port-forward over the Kubernetes API, a leaderelection module for building highly-available controllers, and a separate kubernetes.aio asyncio-based client alongside the default synchronous one.

What You Get

• A generated REST client (kubernetes.client) with typed models and API classes covering every Kubernetes API group and version
• kubernetes.config for loading credentials from a kubeconfig file or from in-cluster service-account tokens automatically
• kubernetes.watch for consuming Kubernetes watch streams (resource create/update/delete events) as a Python iterator
• kubernetes.stream for exec, attach, and port-forward operations against running pods over the Kubernetes API
• A leaderelection module for building highly-available controllers, and a kubernetes.aio package providing an asyncio-native client alongside the default synchronous one

Common Use Cases

• Writing a Kubernetes controller or operator in Python that watches and reconciles custom or core resources
• Building an internal CLI or automation script that creates, updates, or deletes Kubernetes resources programmatically
• Streaming live pod logs or exec-ing into a running container from a Python script or web backend
• Building a dashboard or internal tool that reads cluster state (pods, deployments, nodes) via the generated client
• Writing an asyncio-based Kubernetes controller using the kubernetes.aio client for high-concurrency reconciliation loops

Under The Hood

Architecture - The package splits a large generated surface (kubernetes/client/, produced from the Kubernetes OpenAPI spec via scripts/update-client.sh and the shared swagger.json.unprocessed) from hand-written convenience modules: config/ (credential loading), watch/ (streaming watch events), stream/ (exec/attach/port-forward), leaderelection/ (HA controller support), informer/, dynamic/ (a dynamic, non-generated client for arbitrary/custom resources), and aio/ (the asyncio client built parallel to the sync one).

Tech Stack - Pure Python (99.9%), generated with OpenAPI Generator against the upstream Kubernetes Swagger/OpenAPI spec; the CLIENT_VERSION in setup.py is kept in lockstep with the Kubernetes API version it targets rather than following independent semver.

Code Quality - The kubernetes/e2e_test/ and per-module test/ directories provide both unit and end-to-end coverage (the e2e suite runs against a real or kind-provisioned cluster), and CI/CD is driven by k8s-ci-robot, the shared Kubernetes-org bot, reflecting the project’s integration with upstream Kubernetes release tooling and SIG API Machinery review process.

API Design - Because most of the client is generated directly from the OpenAPI spec, method and model names track the Kubernetes API’s own resource/verb naming exactly (e.g. CoreV1Api.list_namespaced_pod), which is highly consistent but verbose; the hand-written config, watch, stream, and dynamic modules exist specifically to smooth over ergonomics the generated client doesn’t cover on its own (auth loading, streaming, and working with resources not known at generation time).