The kubernetes-client-go repository is the official Go client library for interacting with Kubernetes clusters. Maintained under the OpenShift organization on GitHub, this project provides developers with programmatic access to Kubernetes APIs and cluster management capabilities through Go. The repository serves as a critical bridge between Go applications and Kubernetes infrastructure, enabling developers to build controllers, operators, and other automation tools that need to communicate with Kubernetes API servers.
The client-go library includes several key components for different interaction patterns. The kubernetes package provides the primary clientset for accessing the full Kubernetes API surface. The discovery package enables applications to query which APIs are supported by a particular Kubernetes API server, allowing for dynamic capability detection. The dynamic package offers a generic client that can work with arbitrary Kubernetes API objects without requiring pre-generated type definitions. Authentication is handled through optional plugins in the plugin/pkg/client/auth packages, which support obtaining credentials from external sources. The transport package manages the underlying connection setup and authentication configuration, while the tools/cache package provides utilities specifically designed for writing Kubernetes controllers.
The versioning strategy for client-go reflects its tight coupling with Kubernetes releases. For Kubernetes versions 1.17.0 and later, the project uses v0.x.y semantic versioning tags, while earlier releases use kubernetes-1.x.y tags. The repository maintains multiple release branches corresponding to different Kubernetes minor versions, with active maintenance for recent releases and security-only patches for older branches. The project guarantees at least six months of maintenance for each release branch after its initial stable tag. Bugfixes are backported to older versions, though new features are reserved for the current development branch.
Compatibility between client-go and Kubernetes clusters follows a backwards-compatible model. Older client-go versions can work with newer Kubernetes clusters, and the repository provides a detailed compatibility matrix showing which client-go versions work optimally with specific Kubernetes releases. The HEAD of the master branch tracks the main Kubernetes repository's master branch, ensuring the latest development code is available to users willing to accept potential instability.
The repository's source code originates from the staging area within the main Kubernetes repository at staging/src/k8s.io/client-go. Code development happens in that staging area, and changes are synced to this standalone repository daily. This approach allows the Kubernetes project to maintain client-go as a separate, independently versioned package while keeping it synchronized with core Kubernetes development. Users are directed to submit pull requests against the client packages in the main Kubernetes repository rather than directly to this mirror, ensuring all changes flow through the primary development process.
Installation uses standard Go dependency management with go1.11 or later, and the project provides detailed installation instructions and examples for both in-cluster and out-of-cluster client configurations. The library is classified across multiple domains including development tools, API clients, infrastructure automation, cluster management, and cloud-native applications, reflecting its broad utility in the Kubernetes ecosystem.
