kubernetes/client-go: the Go client library behind most Kubernetes tooling

What client-go is for, and who ends up depending on it

client-go is the Go client for talking to a Kubernetes cluster. That sentence from the README undersells the scope, because the module is not one client but a set of packages: the kubernetes package with the clientset for the Kubernetes API, discovery for enumerating the APIs a server supports, dynamic for generic operations on arbitrary API objects, plugin/pkg/client/auth for optional authentication plugins, transport for setting up auth and starting a connection, and tools/cache for writing controllers. If you are writing a Kubernetes controller, an operator, a CLI that reads cluster state, or a test harness that needs a fake API server, you are probably in the target audience. The repository also ships an examples directory with runnable programs for out-of-cluster and in-cluster client configuration, create-update-delete-deployment, dynamic-create-update-delete-deployment, fake-client, leader-election and workqueue. Those directory names are the fastest map of what the library is expected to do. The audience is narrower than "anyone using Kubernetes": client-go is a Go library, so the people who benefit are Go developers, and everyone else consumes it indirectly through tools written in Go.

How the packages fit together: clientset, dynamic client, informers and the cache

The architecture is visible in the top-level directory listing rather than in prose. A typical program builds a rest.Config, hands it to a clientset constructor, and then calls typed methods on resources. When the resource type is not known at compile time, the dynamic package takes its place and operates on arbitrary Kubernetes API objects. When you need to watch many objects without hammering the API server, informers and listers are the answer, and tools/cache is the package the README names as useful for writing controllers. The cache layer is where the interesting trade-offs live: an informer keeps a local store in sync with the API server and hands you events, so your code reads from memory instead of issuing a request per object. That is why people search for client-go informers and client-go cache together. The cost is state. A cache that drifts, a resync interval that is too aggressive, or a handler that blocks will show up as latency or missed events rather than as an error. The workqueue package exists because controllers need to retry failed keys without spinning, and the leader-election example exists because running two replicas of a controller without coordination is a common way to corrupt your own logic. None of this is enforced by the library. It gives you the primitives and expects you to assemble them correctly.

Installing client-go and running a first out-of-cluster client

The README gives one install command and points at INSTALL.md for detailed instructions and troubleshooting. It states that the fastest way to add the library to a project is to run the following with go1.16 or newer.

go get k8s.io/client-go@latest

After that, the examples directory is where the first real program lives. The out-of-cluster-client-configuration example covers the case where your code runs outside the cluster and reads a kubeconfig; the in-cluster-client-configuration example covers the case where it runs inside a pod. The repository also contains create-update-delete-deployment, dynamic-create-update-delete-deployment, fake-client, leader-election and workqueue examples, and examples/README.md is the index for them. What you should see when you run an example is output from a real call against the cluster your credentials point at. If a listing comes back empty, check the namespace argument and your RBAC rules before suspecting the library. For pinning, the README's guidance is to use the v0.x.y tags for Kubernetes releases from v1.17.0 onward and the kubernetes-1.x.y tags for earlier ones.

Pinning versions is the real work, because v0 means the Go API can break

The README is unusually direct about this: the v0.x.y tags indicate that Go APIs may change in incompatible ways in different versions. There is no stability promise at the import-path level. What the project does promise is a mapping between client-go versions and Kubernetes releases, expressed in a compatibility matrix from Kubernetes 1.29 through 1.34. A check mark means exactly the same features and API objects on both sides. A plus or minus means a partial match: one side has APIs the other does not, while everything in common still works. The README also warns that alpha APIs may vanish or change significantly in a single release, which is the sentence to remember if you depend on anything alpha. Practically, this means your go.mod should pin a client-go tag that corresponds to the cluster version you target, and upgrading the cluster is a reason to revisit the pin. The go.mod in this repository currently declares go 1.27.0, and it carries a godebug line for go1.27, so the module's own toolchain expectation is ahead of the go1.16 minimum the README gives for installation. If you build with an older toolchain than the module declares, expect trouble before you expect a runtime bug.

This repository is a staging area, and that changes how you contribute

The README opens with a warning that this is an automatically published staged repository for Kubernetes, that contributions including issues and pull requests should be made to the main Kubernetes repository, and that this repository is read-only for importing and not used for direct contributions. CONTRIBUTING.md is referenced for details. That is the single most important operational fact about the project and it is easy to miss, because the GitHub repository looks like a normal project with issues and pull requests enabled. If you file a bug here, you are filing it in the wrong place. The maintenance picture is also more granular than a single status label. The README's branch table marks release-1.32, release-1.33, release-1.34 and client-go HEAD with a check meaning changes in the main Kubernetes repo are actively published to client-go by a bot. release-1.31 carries an equals sign, meaning maintenance is manual and only severe security bugs will be patched. release-1.25 through release-1.30 carry a minus sign, which the README labels deprecated, with the note to upgrade. The repository itself is not archived, and the last push was on 2026-09-18, so the staged mirror is current even though you cannot contribute to it directly.

Where client-go is the wrong tool, and what people use instead

client-go is the wrong choice when you are not writing Go. The module is a Go library with Go types; other languages have their own Kubernetes clients, and there is nothing here to bind to. It is also the wrong first stop if what you actually want is to build a controller with opinionated scaffolding: the README positions tools/cache as useful for writing controllers, but it does not give you a controller runtime, a reconciliation loop abstraction, or generated project layout. That is the gap controller-runtime fills, and it is the comparison people search for. The difference in approach is real rather than cosmetic: client-go hands you the clientset, informers, listers and workqueue and expects you to wire the control loop yourself, while controller-runtime builds on the same Kubernetes client foundations and adds a manager, reconciler interfaces and scheme handling so you write less plumbing. Neither is a superset of the other. If you need the dynamic client to operate on arbitrary API objects, or you want the raw informer and workqueue primitives under your own control, client-go is the layer you want. If you want to be told where the reconcile function goes, it is not. A third case: if you only need to read a cluster from a script, kubectl or a client library in your scripting language will get you there with far less code than a compiled Go binary.

Licence, upgrade cost and what the README leaves out

The repository is licensed under Apache-2.0. The practical consequence, without giving legal advice, is that the licence file and any NOTICE requirements travel with the code you redistribute, and that Apache-2.0 includes an explicit patent grant. Read LICENSE and your own legal guidance rather than treating this paragraph as a substitute. On upgrade cost, the README sets the cadence: a new branch and tag for each minor version increment, a new tag only for each patch increment, and a deprecation policy that maintains branches for at least six months after their first stab (the README's sentence is truncated at that point, so the full window is not stated in what is available here). Bugfixes are backported into older client-go versions, but new features are not. That means staying on an old branch buys you security patches and nothing else, and the branch table tells you when a branch has moved to manual maintenance or been marked deprecated. The README does not document a rollback procedure for a client-go upgrade, and it does not describe a migration path between incompatible v0.x.y Go APIs; the CHANGELOG is referenced for a detailed description of changes between versions, which is where you would look before bumping a pin.

Editorial conclusion

Adopt client-go when you are writing Go code that talks to the Kubernetes API directly: the clientset, the dynamic client, informers, listers and the workqueue packages all come from this module. Do not adopt it as a general-purpose Kubernetes toolkit for other languages, and do not expect to file issues or pull requests here, because the README states contributions should go to the main Kubernetes repository and this repository is read-only for importing. Before you commit, verify two things: that the v0.x.y tag you pick matches the Kubernetes version you run against, using the compatibility matrix in the README, and that your go directive is at least 1.16 for the go get path shown there, with go.mod in this repository currently declaring go 1.27.0.

Frequently asked questions

Official sources

1. Issues
2. kubernetes/client-go on GitHub
3. License: Apache-2.0
4. README