The kubernetes/client-go repository is the official Go client library for interacting with Kubernetes clusters. It is a staged repository that is automatically published from the main Kubernetes repository, meaning contributions must be submitted to the primary Kubernetes project rather than directly to this repository. The code is maintained in the staging area of the main Kubernetes repository and synced to this external repository daily.
The library provides several core packages for different aspects of Kubernetes interaction. The kubernetes package contains the clientset for accessing the Kubernetes API, while the discovery package enables detection of APIs supported by a Kubernetes API server. The dynamic package offers a dynamic client for performing generic operations on arbitrary Kubernetes API objects without requiring specific type definitions. Additional packages include plugin/pkg/client/auth for optional authentication plugins that obtain credentials from external sources, the transport package for setting up authentication and connections, and tools/cache which is designed for writing controllers.
Client-go follows a versioning scheme where the major version remains 0 for all releases corresponding to Kubernetes v1.x.y versions. The repository maintains branches for each minor version increment and creates tags for patch versions. Since Kubernetes v1.8.0, version tags from Kubernetes are synced to client-go with a kubernetes- prefix, and from v1.17.0 onward, matching semantic version v0.x.y tags are created for each Kubernetes release. The repository recommends using v0.x.y tags for Kubernetes releases v1.17.0 and later, while kubernetes-1.x.y tags are recommended for earlier releases.
Compatibility is carefully managed across multiple dimensions. Client-go maintains backwards compatibility with older Kubernetes cluster versions since Kubernetes itself is backwards compatible with clients. The repository provides a detailed compatibility matrix showing which client-go versions work with which Kubernetes cluster versions, with most combinations marked as compatible with potential caveats regarding new or removed APIs. Bugfixes are backported to older client-go versions, though new features are not.
The repository maintains active branches for recent Kubernetes releases, with release-1.32, release-1.33, and release-1.34 receiving active maintenance where changes from the main Kubernetes repository are automatically published by a bot. Older branches from release-1.25 through release-1.31 receive manual maintenance with only severe security bugs being patched. The project follows a deprecation policy maintaining branches for at least six months after their first stable tag is cut.
Installation is straightforward using Go's dependency management, with go1.16 or later supporting the command go get k8s.io/client-go@latest. The repository includes detailed installation instructions and troubleshooting guidance in its INSTALL.md file. Examples are provided for both in-cluster client configuration, for applications running as pods within a cluster, and out-of-cluster configuration for external applications. The library is designed to be the standard way for Go applications to programmatically interact with Kubernetes clusters, whether for building operators, controllers, or other Kubernetes-aware tools.
