When you train a large language model with Kubeflow, orchestrate distributed compute with Ray on Google Kubernetes Engine (GKE), serve inference traffic with KServe, or schedule thousands of ML pipeline pods with Apache Airflow, two technologies almost always meet under the hood: Python and Kubernetes.
Python is the undisputed lingua franca of artificial intelligence and machine learning. Kubernetes is the de facto operating system for AI infrastructure—scheduling GPUs and TPUs, orchestrating distributed training jobs, and scaling model serving endpoints. Connecting these two worlds is the official Kubernetes Python client (kubernetes-client/python).
Second only to Kubernetes's in-tree Go client (client-go) in popularity, the Kubernetes Python client is downloaded more than 73 million times per month on PyPI (~1.7 million times a day) and has earned over 7,500 GitHub stars.
Yet for the past several years, this critical bridge between Python and Kubernetes has operated in low-maintenance mode. As AI/ML workloads have exploded in scale and complexity, the gap between what modern AI infrastructure demands and what the legacy Python client was built to deliver has become impossible to ignore.
Today, we're sharing how Google Cloud engineers are partnering with open source contributors in Kubernetes SIG API Machinery to modernize the official Kubernetes Python client for the AI/ML era.
The historical problem: Legacy machinery meets hyperscale AI
As AI/ML clusters grew from dozens of nodes to 50,000-node hyperscale environments, the limitations of the Python client's aging architecture began surfacing as real-world production bottlenecks:
- Frozen on a decommissioned code generator: Up through Kubernetes 1.35, the Python client generated its ~400,000 lines of API and model code using OpenAPI Generator v4.3.0 (
python-legacy)—a generator version that was deprecated in 2020 and completely removed from the upstream OpenAPI Generator project in May 2022. Staying pinned to v4.3.0 meant the client accumulatedDeprecationWarningdebt across newer Python releases, struggled with modern dependency resolution alongside PyTorch and TensorFlow, and couldn't easily receive upstream generator bug fixes. - Synchronous-only execution in an
asyncioworld: Modern Python web frameworks, inference servers, and orchestrators have overwhelmingly shifted toasyncioto handle high-concurrency I/O without being bottlenecked by Python's Global Interpreter Lock (GIL). Because the official client lacked nativeasynciosupport from the start, users were forced to turn to community clients likekubernetes-asyncioor third-party clients (kr8s,lightkube). - Missing controller primitives (
SharedInformer): In Go, controllers useSharedInformerto maintain a local, event-driven cache of cluster resources without repeatedly pollingkube-apiserver. Without an equivalent primitive in Python, applications watching thousands of training pods or custom resources often hammered the API server or ran into watch disconnects. - Slow model deserialization and HTTP/1.1 transport limits: In large clusters, listing pods or nodes in Python could take 30+ seconds due to excessive model reconfiguration during JSON deserialization (issue #1921). Combined with an underlying
urllib3transport layer restricted to HTTP/1.1, Python workloads missed out on the HTTP/2 multiplexing, flow control, and binary framing that makeclient-gofast at scale.
A principled approach: Built for AI/ML, not 1:1 parity
When we set out to modernize the Kubernetes Python client, we established two guiding principles to ensure our engineering investments deliver the highest possible return for the community:
- Target high-impact gaps, not 1:1
client-goparity:client-gois the in-tree Kubernetes client used by the control plane itself (kube-controller-manager,kube-scheduler, and in-tree controllers). Attempting to replicate every long-tailclient-gofeature in Python would yield diminishing returns. Instead, we focus strictly on the primitives Python developers and operators actually need in production. - Prioritize AI/ML workload requirements: Because AI/ML training, inference, and batch frameworks are the primary drivers of Python on Kubernetes today, every architectural improvement—from async concurrency and CRD ergonomics to large-cluster list performance—is prioritized through the lens of AI/ML scale.
How we're modernizing the Kubernetes Python client
Our roadmap focuses on three technical pillars: Machinery, Features, and Performance.
1. Machinery: Upgrading to OpenAPI Generator v7.20+
Every improvement to the Python client starts with its code generation pipeline (kubernetes-client/gen). Over the past few years, multiple community attempts to migrate off the decommissioned v4.3.0 python-legacy generator stalled due to the sheer scale of template and schema changes across hundreds of Kubernetes API models.
We are actively driving the migration to OpenAPI Generator v7.20.0+ and establishing continuous tracking with upstream generator releases. Completing this foundational upgrade:
- Replaces dead
python-legacytemplates with actively maintained v7+ Python code generation. - Modernizes type annotations and packaging metadata, easing
pipdependency resolution alongside heavy ML frameworks. - Unlocks the ability to contribute performance and serialization fixes directly to upstream OpenAPI Generator templates.
2. Features: Native asyncio, Shared Informers, and WebSocket v5
To prevent ecosystem fragmentation and give Python developers first-class Kubernetes primitives out of the box, we are bringing three major capabilities to the official client:
- Official
asynciosupport: Rather than forcing developers to choose between the official synchronous client and third-party async libraries, we are introducing officialasynciosupport directly intokubernetes-client/python. Async-first ML orchestrators, FastAPI-based model control planes, and notebooks will be able to issue concurrent, non-blocking Kubernetes API calls natively. - Shared Informers (
kubernetes-client/python#2515): We are bringing theSharedInformerpattern to the Python client. With built-in list-watch caching, automatic reconnection, and resource event handlers (on_add,on_update,on_delete), Python controllers and AI job managers can monitor cluster state and Custom Resources (TrainJob,RayCluster,InferenceService) with a fraction of the memory footprint and API server load. - WebSocket v5 streaming (KEP-4006,
kubernetes-client/python#2486): As upstream Kubernetes transitions remote command streaming (exec,attach,port-forward) away from legacy SPDY to standard WebSockets via thev5.channel.k8s.iosubprotocol, we are adding native WebSocket v5 channel support so interactive debugging and remote job execution work seamlessly against modern control planes.
3. Performance: Slashing deserialization overhead
For AI/ML platforms operating on multi-thousand-node clusters, client performance is an availability requirement. Our performance track targets the largest bottlenecks in Python client execution:
- Eliminating model reconfiguration overhead: When deserializing large JSON responses (such as listing tens of thousands of Pods across a training cluster), the legacy generated model layer repeatedly instantiates and reconfigures schema validation objects (issue #1921). With the move to OpenAPI Generator v7+, we are revamping model initialization so large cluster queries deserialize in a fraction of the time.
What's next and how to get involved
The intersection of Python and Kubernetes is where modern AI infrastructure is built. By modernizing the code generation machinery, adding native asyncio and SharedInformer primitives, and closing the deserialization performance gap, we aim to give every ML engineer and platform builder a fast, reliable, and Pythonic official client—whether they are running a single notebook experiment or orchestrating a 50,000-node GKE training fleet.
This effort is happening in the open under Kubernetes SIG API Machinery, and we welcome feedback, use cases, and contributions from the community:
- Explore the repository and roadmap: Check out
kubernetes-client/pythonandkubernetes-client/genon GitHub. - Join the conversation: Connect with us in the
#sig-api-machinerychannel on Kubernetes Slack or at the bi-weekly Kubernetes Python client triage meetings.







