client-go Documentation

The client-go library provides several packages for interacting with Kubernetes:

• kubernetes: Contains the clientset to access the Kubernetes API.
• discovery: Used to discover APIs supported by a Kubernetes API server.
• dynamic: Provides a dynamic client for performing generic operations on arbitrary Kubernetes API objects.
• plugin/pkg/client/auth: Contains optional authentication plugins for obtaining credentials from external sources.
• transport: Used to set up authentication and establish connections.
• tools/cache: Useful for writing Kubernetes controllers.

When working with specific Kubernetes clusters, you should match your client-go version to your Kubernetes version using the appropriate tag format:

• For Kubernetes >= v1.17.0: Use the v0.x.y tag format. (e.g., Kubernetes v1.20.4 uses k8s.io/client-go@v0.20.4).
• For Kubernetes < v1.17.0: Use the kubernetes-1.x.y tag format. (e.g., Kubernetes v1.16.3 uses k8s.io/client-go@kubernetes-1.16.3).

After running the command, run go mod tidy to finalize the dependency in your go.mod file.

Versioning Convention

• For each v1.x.y Kubernetes release, the client-go major version (first digit) remains 0 (e.g., v0.x.y).
• Bugfixes update the patch version (third digit).
• New minor versions result in new branches and tags.

Compatibility

• Your code <-> client-go: The v0.x.y tags indicate that Go APIs may change in incompatible ways between versions. Use specific version requirements in your dependency management to avoid breaking changes.
• client-go <-> Kubernetes clusters: Kubernetes is backwards compatible with clients. Older client-go versions will work with many different Kubernetes cluster versions. Bugfixes are backported to older versions, but new features are not.

To build resilient controllers, follow the event-driven, cached model provided by tools/cache. This pattern decouples event detection from reconciliation:

1. Reflector: Performs a LIST and then a WATCH to stream changes.
2. Informer/Indexer: Populates a local cache (Indexer) and triggers Event Handlers.
3. WorkQueue: Event handlers should only add the object's key to a util/workqueue. This prevents blocking the watch stream.
4. Controller: The controller processes keys from the WorkQueue and uses a Lister to read data from the Indexer cache.

This architecture allows the controller to perform retries with exponential backoff without impacting the underlying WATCH stream.

The method for configuring the client depends on where your application is running:

• In-Cluster: If your application runs inside a Pod within a Kubernetes cluster, use the in-cluster configuration pattern.
• Out-of-Cluster: If your application runs outside the cluster (e.g., on your local machine), use the out-of-cluster configuration pattern.

Refer to the specific examples in the repository for implementation details: examples/in-cluster-client-configuration and examples/out-of-cluster-client-configuration.

The rest.Config object is the in-memory representation of your Kubernetes client configuration. To produce this object, use the tools/clientcmd package, which handles the complexity of parsing kubeconfig files, merging contexts, and managing external authentication providers like OIDC.

To control client-side rate limiting and interact with the server's API Priority and Fairness system, configure the following fields in your rest.Config:

• QPS: The client-side rate limit.
• Burst: The burst capacity for requests.

To use the latest version of client-go, ensure you are using Go 1.16 or later and run the go get command. This will add k8s.io/client-go to your Go module. You can then run go mod tidy or perform a build/test/run to download dependencies and update your go.mod file.

go get k8s.io/client-go@latest

To add client-go to your Go project, use the go get command. Ensure you are using Go 1.16+ for the latest version or Go 1.11+ for specific versions.

Install the latest version

go get k8s.io/client-go@latest

Install a specific version

go get k8s.io/client-go@v0.20.4

If you encounter the error module k8s.io/client-go@latest found (v1.5.2), but does not contain package k8s.io/client-go/..., it indicates you are using a Go version older than 1.16. You must explicitly specify a version instead of using @latest.

go get k8s.io/client-go@v0.20.4