Skip to content

Commit cb93d6e

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request kubernetes#129212 from Jefftree/add-clientgo-readme
Add client-go README
2 parents be1c991 + 8f782fe commit cb93d6e

File tree

1 file changed

+188
-0
lines changed

1 file changed

+188
-0
lines changed

‎staging/src/k8s.io/client-go/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# client-go
2+
3+
Go clients for talking to a [kubernetes](http://kubernetes.io/) cluster.
4+
5+
We recommend using the `v0.x.y` tags for Kubernetes releases >= `v1.17.0` and
6+
`kubernetes-1.x.y` tags for Kubernetes releases < `v1.17.0`.
7+
8+
The fastest way to add this library to a project is to run `go get k8s.io/client-go@latest` with go1.16+.
9+
See [INSTALL.md](/INSTALL.md) for detailed installation instructions and troubleshooting.
10+
11+
[![GoDocWidget]][GoDocReference]
12+
13+
[GoDocWidget]: https://godoc.org/k8s.io/client-go?status.svg
14+
[GoDocReference]:https://godoc.org/k8s.io/client-go
15+
16+
## Table of Contents
17+
18+
- [What's included](#whats-included)
19+
- [Versioning](#versioning)
20+
- [Compatibility: your code <-> client-go](#compatibility-your-code---client-go)
21+
- [Compatibility: client-go <-> Kubernetes clusters](#compatibility-client-go---kubernetes-clusters)
22+
- [Compatibility matrix](#compatibility-matrix)
23+
- [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)
24+
- [Kubernetes tags](#kubernetes-tags)
25+
- [How to get it](#how-to-get-it)
26+
- [How to use it](#how-to-use-it)
27+
- [Dependency management](#dependency-management)
28+
- [Contributing code](#contributing-code)
29+
30+
### What's included
31+
32+
* The `kubernetes` package contains the clientset to access Kubernetes API.
33+
* The `discovery` package is used to discover APIs supported by a Kubernetes API server.
34+
* The `dynamic` package contains a dynamic client that can perform generic operations on arbitrary Kubernetes API objects.
35+
* The `plugin/pkg/client/auth` packages contain optional authentication plugins for obtaining credentials from external sources.
36+
* The `transport` package is used to set up auth and start a connection.
37+
* The `tools/cache` package is useful for writing controllers.
38+
39+
### Versioning
40+
41+
- For each `v1.x.y` Kubernetes release, the major version (first digit)
42+
would remain `0`.
43+
44+
- Bugfixes will result in the patch version (third digit) changing. PRs that are
45+
cherry-picked into an older Kubernetes release branch will result in an update
46+
to the corresponding branch in `client-go`, with a corresponding new tag
47+
changing the patch version.
48+
49+
#### Branches and tags.
50+
51+
We will create a new branch and tag for each increment in the minor version
52+
number. We will create only a new tag for each increment in the patch
53+
version number. See [semver](http://semver.org/) for definitions of major,
54+
minor, and patch.
55+
56+
The HEAD of the master branch in client-go will track the HEAD of the master
57+
branch in the main Kubernetes repo.
58+
59+
#### Compatibility: your code <-> client-go
60+
61+
The `v0.x.y` tags indicate that go APIs may change in incompatible ways in
62+
different versions.
63+
64+
See [INSTALL.md](INSTALL.md) for guidelines on requiring a specific
65+
version of client-go.
66+
67+
#### Compatibility: client-go <-> Kubernetes clusters
68+
69+
Since Kubernetes is backwards compatible with clients, older `client-go`
70+
versions will work with many different Kubernetes cluster versions.
71+
72+
We will backport bugfixes--but not new features--into older versions of
73+
`client-go`.
74+
75+
76+
#### Compatibility matrix
77+
78+
| | Kubernetes 1.23 | Kubernetes 1.24 | Kubernetes 1.25 | Kubernetes 1.26 | Kubernetes 1.27 | Kubernetes 1.28 |
79+
| ----------------------------- | --------------- | --------------- | --------------- | --------------- | --------------- | --------------- |
80+
| `kubernetes-1.23.0`/`v0.23.0` | ✓ | +- | +- | +- | +- | +- |
81+
| `kubernetes-1.24.0`/`v0.24.0` | +- | ✓ | +- | +- | +- | +- |
82+
| `kubernetes-1.25.0`/`v0.25.0` | +- | +- | ✓ | +- | +- | +- |
83+
| `kubernetes-1.26.0`/`v0.26.0` | +- | +- | +- | ✓ | +- | +- |
84+
| `kubernetes-1.27.0`/`v0.27.0` | +- | +- | +- | +- | ✓ | +- |
85+
| `kubernetes-1.28.0`/`v0.28.0` | +- | +- | +- | +- | +- | ✓ |
86+
| `HEAD` | +- | +- | +- | +- | +- | +- |
87+
88+
Key:
89+
90+
* `✓` Exactly the same features / API objects in both client-go and the Kubernetes
91+
version.
92+
* `+` client-go has features or API objects that may not be present in the
93+
Kubernetes cluster, either due to that client-go has additional new API, or
94+
that the server has removed old API. However, everything they have in
95+
common (i.e., most APIs) will work. Please note that alpha APIs may vanish or
96+
change significantly in a single release.
97+
* `-` The Kubernetes cluster has features the client-go library can't use,
98+
either due to the server has additional new API, or that client-go has
99+
removed old API. However, everything they share in common (i.e., most APIs)
100+
will work.
101+
102+
See the [CHANGELOG](./CHANGELOG.md) for a detailed description of changes
103+
between client-go versions.
104+
105+
| Branch | Canonical source code location | Maintenance status |
106+
| -------------- | ----------------------------------- | ------------------ |
107+
| `release-1.19` | Kubernetes main repo, 1.19 branch | =- |
108+
| `release-1.20` | Kubernetes main repo, 1.20 branch | =- |
109+
| `release-1.21` | Kubernetes main repo, 1.21 branch | =- |
110+
| `release-1.22` | Kubernetes main repo, 1.22 branch | =- |
111+
| `release-1.23` | Kubernetes main repo, 1.23 branch | =- |
112+
| `release-1.24` | Kubernetes main repo, 1.24 branch | =- |
113+
| `release-1.25` | Kubernetes main repo, 1.25 branch | ✓ |
114+
| `release-1.26` | Kubernetes main repo, 1.26 branch | ✓ |
115+
| `release-1.27` | Kubernetes main repo, 1.27 branch | ✓ |
116+
| `release-1.28` | Kubernetes main repo, 1.28 branch | ✓ |
117+
| client-go HEAD | Kubernetes main repo, master branch | ✓ |
118+
119+
Key:
120+
121+
* `✓` Changes in main Kubernetes repo are actively published to client-go by a bot
122+
* `=` Maintenance is manual, only severe security bugs will be patched.
123+
* `-` Deprecated; please upgrade.
124+
125+
#### Deprecation policy
126+
127+
We will maintain branches for at least six months after their first stable tag
128+
is cut. (E.g., the clock for the release-2.0 branch started ticking when we
129+
tagged v2.0.0, not when we made the first alpha.) This policy applies to
130+
every version greater than or equal to 2.0.
131+
132+
#### Why do the 1.4 and 1.5 branch contain top-level folder named after the version?
133+
134+
For the initial release of client-go, we thought it would be easiest to keep
135+
separate directories for each minor version. That soon proved to be a mistake.
136+
We are keeping the top-level folders in the 1.4 and 1.5 branches so that
137+
existing users won't be broken.
138+
139+
### Kubernetes tags
140+
141+
This repository is still a mirror of
142+
[k8s.io/kubernetes/staging/src/client-go](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/client-go),
143+
the code development is still done in the staging area.
144+
145+
Since Kubernetes `v1.8.0`, when syncing the code from the staging area,
146+
we also sync the Kubernetes version tags to client-go, prefixed with
147+
`kubernetes-`. From Kubernetes `v1.17.0`, we also create matching semver
148+
`v0.x.y` tags for each `v1.x.y` Kubernetes release.
149+
150+
For example, if you check out the `kubernetes-1.17.0` or the `v0.17.0` tag in
151+
client-go, the code you get is exactly the same as if you check out the `v1.17.0`
152+
tag in Kubernetes, and change directory to `staging/src/k8s.io/client-go`.
153+
154+
The purpose is to let users quickly find matching commits among published repos,
155+
like [sample-apiserver](https://github.com/kubernetes/sample-apiserver),
156+
[apiextension-apiserver](https://github.com/kubernetes/apiextensions-apiserver),
157+
etc. The Kubernetes version tag does NOT claim any backwards compatibility
158+
guarantees for client-go. Please check the [semantic versions](#versioning) if
159+
you care about backwards compatibility.
160+
161+
### How to get it
162+
163+
To get the latest version, use go1.16+ and fetch using the `go get` command. For example:
164+
165+
```
166+
go get k8s.io/client-go@latest
167+
```
168+
169+
To get a specific version, use go1.11+ and fetch the desired version using the `go get` command. For example:
170+
171+
```
172+
go get k8s.io/[email protected]
173+
```
174+
175+
See [INSTALL.md](/INSTALL.md) for detailed instructions and troubleshooting.
176+
177+
### How to use it
178+
179+
If your application runs in a Pod in the cluster, please refer to the
180+
in-cluster [example](examples/in-cluster-client-configuration), otherwise please
181+
refer to the out-of-cluster [example](examples/out-of-cluster-client-configuration).
182+
183+
### Dependency management
184+
185+
For details on how to correctly use a dependency management for installing client-go, please see [INSTALL.md](INSTALL.md).
186+
187+
### Contributing code
188+
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.

0 commit comments

Comments
 (0)