The official Kubernetes Python client is downloaded 73 million times a month. Until last week, it was generating all 400,000 lines of its API code from a code generator deprecated in 2020 and removed entirely in 2022. Google Cloud engineers and Kubernetes SIG API Machinery just fixed that — and brought native asyncio, SharedInformers, and WebSocket v5 along for the ride.
The Dirty Secret of the Most-Downloaded Kubernetes Client
The kubernetes Python package runs on OpenAPI Generator v4.3.0, the python-legacy flavor. That generator was deprecated four years ago and pulled from the upstream project in May 2022. The Kubernetes client kept using it anyway — not out of neglect, but because migrating 400,000 auto-generated lines across hundreds of API models is a project-sized lift. Multiple community migration attempts stalled for exactly that reason.
The practical fallout was real. The stale codegen caused DeprecationWarning noise on modern Python releases, broke dependency resolution alongside PyTorch and TensorFlow, and made it impossible to pull in upstream serialization fixes. Listing pods or nodes on a large cluster could take 30 seconds or more — not a slowness issue, an availability issue for teams running 50,000-node GKE training fleets.
What the Modernization Delivers
Official asyncio: kubernetes.aio
The absence of native async support was the most common reason Python engineers reached for third-party Kubernetes clients. kubernetes-asyncio, kr8s, and lightkube exist primarily because the official library was synchronous-only. The problem with that workaround: third-party clients can lag on new API features; the official client auto-generates from the full Kubernetes OpenAPI spec and never will.
The new kubernetes.aio module fixes this cleanly. No new dependency. No third-party parity concerns. FastAPI-based model control planes, Jupyter notebooks, and async inference orchestrators can now talk to the Kubernetes API natively:
from kubernetes import config
from kubernetes.aio import ApiClient
from kubernetes import client
async def list_pods():
await config.load_kube_config()
async with ApiClient() as api:
v1 = client.CoreV1Api(api)
pods = await v1.list_pod_for_all_namespaces()
return pods.itemsSharedInformers: What Python Controllers Have Always Needed
Go developers have had the SharedInformer pattern from client-go for years. Python never did. The result: Python-based Kubernetes controllers either polled the API server continuously — hammering it at scale — or opened individual watches per consumer and hoped for the best.
The new SharedInformer implementation (PR #2515) brings the full pattern to Python: list-watch caching with automatic reconnection, and on_add, on_update, and on_delete event handlers. Only one watch is opened per resource type regardless of how many consumers are listening. For teams building PyTorch training job controllers or custom ML operators, this is the primitive that makes well-behaved Python controllers possible.
Performance and Protocol Updates
The deserialization bottleneck is gone. The root cause was the legacy codegen triggering excessive model reconfiguration during JSON parsing — a problem that only surfaced at scale. The v7+ generator revamps model initialization, bringing large-cluster list times from 30-plus seconds down to seconds.
The library also adds native WebSocket v5 support (KEP-4006, PR #2486), transitioning exec, attach, and port-forward from SPDY — a protocol deprecated by Google in 2015 — to standard WebSockets. This is a compatibility requirement as more Kubernetes control planes phase out SPDY entirely.
Upgrading: No Breaking Changes
The synchronous API is unchanged. The kubernetes.aio module is additive. The codegen migration, deserialization fixes, and WebSocket v5 support are all transparent. This is as close to a free upgrade as the Python ecosystem gets. Install the latest version, run your existing code, and add async usage incrementally where it matters.
Community channel for questions: #sig-api-machinery on Kubernetes Slack. Full details in the Google Open Source Blog announcement.
Why This Matters for ML Infrastructure
Kubernetes is where large-scale ML training runs. Python is how ML engineers write everything else. The official client being stuck on deprecated machinery was a quiet tax on every Kubeflow pipeline, every custom training operator, every notebook that needed to query cluster state. The Kubeflow SDK alone crossed one million downloads earlier this year — all of it ultimately backed by this client.
This modernization does not ship a flashy new feature. It ships the infrastructure that lets the right features exist. For ML infrastructure teams, that is the kind of work that matters most. Check the official repository for the updated installation instructions.
