diff --git a/README.md b/README.md new file mode 100644 index 00000000..1e6be434 --- /dev/null +++ b/README.md @@ -0,0 +1,188 @@ +# client-go + +Go clients for talking to a [kubernetes](http://kubernetes.io/) cluster. + +We recommend using the `v0.x.y` tags for Kubernetes releases >= `v1.17.0` and +`kubernetes-1.x.y` tags for Kubernetes releases < `v1.17.0`. + +The fastest way to add this library to a project is to run `go get k8s.io/client-go@latest` with go1.16+. +See [INSTALL.md](/INSTALL.md) for detailed installation instructions and troubleshooting. + +[![GoDocWidget]][GoDocReference] + +[GoDocWidget]: https://godoc.org/k8s.io/client-go?status.svg +[GoDocReference]:https://godoc.org/k8s.io/client-go + +## Table of Contents + +- [What's included](#whats-included) +- [Versioning](#versioning) + - [Compatibility: your code <-> client-go](#compatibility-your-code---client-go) + - [Compatibility: client-go <-> Kubernetes clusters](#compatibility-client-go---kubernetes-clusters) + - [Compatibility matrix](#compatibility-matrix) + - [Why do the 1.4 and 1.5 branch contain top-level folder named after the version?](#why-do-the-14-and-15-branch-contain-top-level-folder-named-after-the-version) +- [Kubernetes tags](#kubernetes-tags) +- [How to get it](#how-to-get-it) +- [How to use it](#how-to-use-it) +- [Dependency management](#dependency-management) +- [Contributing code](#contributing-code) + +### What's included + +* The `kubernetes` package contains the clientset to access Kubernetes API. +* The `discovery` package is used to discover APIs supported by a Kubernetes API server. +* The `dynamic` package contains a dynamic client that can perform generic operations on arbitrary Kubernetes API objects. +* The `plugin/pkg/client/auth` packages contain optional authentication plugins for obtaining credentials from external sources. +* The `transport` package is used to set up auth and start a connection. +* The `tools/cache` package is useful for writing controllers. + +### Versioning + +- For each `v1.x.y` Kubernetes release, the major version (first digit) +would remain `0`. + +- Bugfixes will result in the patch version (third digit) changing. PRs that are +cherry-picked into an older Kubernetes release branch will result in an update +to the corresponding branch in `client-go`, with a corresponding new tag +changing the patch version. + +#### Branches and tags. + +We will create a new branch and tag for each increment in the minor version +number. We will create only a new tag for each increment in the patch +version number. See [semver](http://semver.org/) for definitions of major, +minor, and patch. + +The HEAD of the master branch in client-go will track the HEAD of the master +branch in the main Kubernetes repo. + +#### Compatibility: your code <-> client-go + +The `v0.x.y` tags indicate that go APIs may change in incompatible ways in +different versions. + +See [INSTALL.md](INSTALL.md) for guidelines on requiring a specific +version of client-go. + +#### Compatibility: client-go <-> Kubernetes clusters + +Since Kubernetes is backwards compatible with clients, older `client-go` +versions will work with many different Kubernetes cluster versions. + +We will backport bugfixes--but not new features--into older versions of +`client-go`. + + +#### Compatibility matrix + +| | Kubernetes 1.23 | Kubernetes 1.24 | Kubernetes 1.25 | Kubernetes 1.26 | Kubernetes 1.27 | Kubernetes 1.28 | +| ----------------------------- | --------------- | --------------- | --------------- | --------------- | --------------- | --------------- | +| `kubernetes-1.23.0`/`v0.23.0` | ✓ | +- | +- | +- | +- | +- | +| `kubernetes-1.24.0`/`v0.24.0` | +- | ✓ | +- | +- | +- | +- | +| `kubernetes-1.25.0`/`v0.25.0` | +- | +- | ✓ | +- | +- | +- | +| `kubernetes-1.26.0`/`v0.26.0` | +- | +- | +- | ✓ | +- | +- | +| `kubernetes-1.27.0`/`v0.27.0` | +- | +- | +- | +- | ✓ | +- | +| `kubernetes-1.28.0`/`v0.28.0` | +- | +- | +- | +- | +- | ✓ | +| `HEAD` | +- | +- | +- | +- | +- | +- | + +Key: + +* `✓` Exactly the same features / API objects in both client-go and the Kubernetes + version. +* `+` client-go has features or API objects that may not be present in the + Kubernetes cluster, either due to that client-go has additional new API, or + that the server has removed old API. However, everything they have in + common (i.e., most APIs) will work. Please note that alpha APIs may vanish or + change 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 has + removed old API. However, everything they share in common (i.e., most APIs) + will work. + +See the [CHANGELOG](./CHANGELOG.md) for a detailed description of changes +between client-go versions. + +| Branch | Canonical source code location | Maintenance status | +| -------------- | ----------------------------------- | ------------------ | +| `release-1.19` | Kubernetes main repo, 1.19 branch | =- | +| `release-1.20` | Kubernetes main repo, 1.20 branch | =- | +| `release-1.21` | Kubernetes main repo, 1.21 branch | =- | +| `release-1.22` | Kubernetes main repo, 1.22 branch | =- | +| `release-1.23` | Kubernetes main repo, 1.23 branch | =- | +| `release-1.24` | Kubernetes main repo, 1.24 branch | =- | +| `release-1.25` | Kubernetes main repo, 1.25 branch | ✓ | +| `release-1.26` | Kubernetes main repo, 1.26 branch | ✓ | +| `release-1.27` | Kubernetes main repo, 1.27 branch | ✓ | +| `release-1.28` | Kubernetes main repo, 1.28 branch | ✓ | +| client-go HEAD | Kubernetes main repo, master branch | ✓ | + +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. + +#### Deprecation policy + +We will maintain branches for at least six months after their first stable tag +is cut. (E.g., the clock for the release-2.0 branch started ticking when we +tagged v2.0.0, not when we made the first alpha.) This policy applies to +every version greater than or equal to 2.0. + +#### Why do the 1.4 and 1.5 branch contain top-level folder named after the version? + +For the initial release of client-go, we thought it would be easiest to keep +separate 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 that +existing users won't be broken. + +### Kubernetes tags + +This repository is still a mirror of +[k8s.io/kubernetes/staging/src/client-go](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/client-go), +the code development is still done in the staging area. + +Since Kubernetes `v1.8.0`, when syncing the code from the staging area, +we also sync the Kubernetes version tags to client-go, prefixed with +`kubernetes-`. From Kubernetes `v1.17.0`, we also create matching semver +`v0.x.y` tags for each `v1.x.y` Kubernetes release. + +For example, if you check out the `kubernetes-1.17.0` or the `v0.17.0` tag in +client-go, the code you get is exactly the same as if you check out the `v1.17.0` +tag in Kubernetes, and change directory to `staging/src/k8s.io/client-go`. + +The purpose is to let users quickly find matching commits among published repos, +like [sample-apiserver](https://github.com/kubernetes/sample-apiserver), +[apiextension-apiserver](https://github.com/kubernetes/apiextensions-apiserver), +etc. The Kubernetes version tag does NOT claim any backwards compatibility +guarantees for client-go. Please check the [semantic versions](#versioning) if +you care about backwards compatibility. + +### How to get it + +To get the latest version, use go1.16+ and fetch using the `go 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 the `go get` command. For example: + +``` +go get k8s.io/client-go@v0.20.4 +``` + +See [INSTALL.md](/INSTALL.md) for detailed instructions and troubleshooting. + +### How to use it + +If your application runs in a Pod in the cluster, please refer to the +in-cluster [example](examples/in-cluster-client-configuration), otherwise please +refer to the out-of-cluster [example](examples/out-of-cluster-client-configuration). + +### Dependency management + +For details on how to correctly use a dependency management for installing client-go, please see [INSTALL.md](INSTALL.md). + +### Contributing code +Please send pull requests against the client packages in the Kubernetes main [repository](https://github.com/kubernetes/kubernetes). Changes in the staging area will be published to this repository every day.