Repository files navigation

Go clients for talking to akubernetes cluster.

We recommend using thev0.x.y tags for Kubernetes releases >=v1.17.0 andkubernetes-1.x.y tags for Kubernetes releases <v1.17.0.

The fastest way to add this library to a project is to rungo get k8s.io/client-go@latest with go1.16+.SeeINSTALL.md for detailed installation instructions and troubleshooting.

• What's included
• Versioning
  • Compatibility: your code <-> client-go
  • Compatibility: client-go <-> Kubernetes clusters
  • Compatibility matrix
  • Why do the 1.4 and 1.5 branch contain top-level folder named after the version?
• Kubernetes tags
• How to get it
• How to use it
• Dependency management
• Contributing code

• Thekubernetes package contains the clientset to access Kubernetes API.
• Thediscovery package is used to discover APIs supported by a Kubernetes API server.
• Thedynamic package contains a dynamic client that can perform generic operations on arbitrary Kubernetes API objects.
• Theplugin/pkg/client/auth packages contain optional authentication plugins for obtaining credentials from external sources.
• Thetransport package is used to set up auth and start a connection.
• Thetools/cache package is useful for writing controllers.

• For eachv1.x.y Kubernetes release, the major version (first digit)would remain0.

• Bugfixes will result in the patch version (third digit) changing. PRs that arecherry-picked into an older Kubernetes release branch will result in an updateto the corresponding branch inclient-go, with a corresponding new tagchanging the patch version.

We will create a new branch and tag for each increment in the minor versionnumber. We will create only a new tag for each increment in the patchversion number. Seesemver for definitions of major,minor, and patch.

The HEAD of the master branch in client-go will track the HEAD of the masterbranch in the main Kubernetes repo.

Thev0.x.y tags indicate that go APIs may change in incompatible ways indifferent versions.

SeeINSTALL.md for guidelines on requiring a specificversion of client-go.

Since Kubernetes is backwards compatible with clients, olderclient-goversions will work with many different Kubernetes cluster versions.

We will backport bugfixes--but not new features--into older versions ofclient-go.

Key:

• ✓ Exactly the same features / API objects in both client-go and the Kubernetesversion.
• + client-go has features or API objects that may not be present in theKubernetes cluster, either due to that client-go has additional new API, orthat the server has removed old API. However, everything they have incommon (i.e., most APIs) will work. Please note that alpha APIs may vanish orchange significantly in a single release.
• - The Kubernetes cluster has features the client-go library can't use,either due to the server has additional new API, or that client-go hasremoved old API. However, everything they share in common (i.e., most APIs)will work.

See theCHANGELOG for a detailed description of changesbetween client-go versions.

Key:

• ✓ Changes in main Kubernetes repo are actively published to client-go by a bot
• = Maintenance is manual, only severe security bugs will be patched.
• - Deprecated; please upgrade.

We will maintain branches for at least six months after their first stable tagis cut. (E.g., the clock for the release-2.0 branch started ticking when wetagged v2.0.0, not when we made the first alpha.) This policy applies toevery version greater than or equal to 2.0.

For the initial release of client-go, we thought it would be easiest to keepseparate directories for each minor version. That soon proved to be a mistake.We are keeping the top-level folders in the 1.4 and 1.5 branches so thatexisting users won't be broken.

This repository is still a mirror ofk8s.io/kubernetes/staging/src/client-go,the code development is still done in the staging area.

Since Kubernetesv1.8.0, when syncing the code from the staging area,we also sync the Kubernetes version tags to client-go, prefixed withkubernetes-. From Kubernetesv1.17.0, we also create matching semverv0.x.y tags for eachv1.x.y Kubernetes release.

For example, if you check out thekubernetes-1.17.0 or thev0.17.0 tag inclient-go, the code you get is exactly the same as if you check out thev1.17.0tag in Kubernetes, and change directory tostaging/src/k8s.io/client-go.

The purpose is to let users quickly find matching commits among published repos,likesample-apiserver,apiextension-apiserver,etc. The Kubernetes version tag does NOT claim any backwards compatibilityguarantees for client-go. Please check thesemantic versions ifyou care about backwards compatibility.

To get the latest version, use go1.16+ and fetch using thego get command. For example:

go get k8s.io/client-go@latest

To get a specific version, use go1.11+ and fetch the desired version using thego get command. For example:

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

SeeINSTALL.md for detailed instructions and troubleshooting.

If your application runs in a Pod in the cluster, please refer to thein-clusterexample, otherwise pleaserefer to the out-of-clusterexample.

For details on how to correctly use a dependency management for installing client-go, please seeINSTALL.md.

Please send pull requests against the client packages in the Kubernetes mainrepository. Changes in the staging area will be published to this repository every day.