github/client-go
1
0
Fork 0
mirror of https://github.com/kubernetes/client-go.git synced 2025-06-28 16:07:29 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #99741 from liggitt/client-go-install

Browse Source 
Update client-go install instructions

Kubernetes-commit: 4d5868afc3f2ba2f9fb6a31fd9c47a04784a07fc
This commit is contained in:
Kubernetes Publisher 2021-03-04 02:08:56 -08:00
commit 9409f5796d
1 changed files with 71 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
INSTALL.md
View File

@ -1,13 +1,11 @@
# Installing client-go
## For the casual user
## Using the latest version
If you want to write a simple script, don't care about a reproducible client
library install, don't mind getting HEAD (which may be less stable than a
particular release), then simply:
If you want to use the latest version of this library, use go1.16+ and run:
```sh
go get k8s.io/client-go@master
go get k8s.io/client-go@latest
```
This will record a dependency on `k8s.io/client-go` in your go module.
@ -17,25 +15,76 @@ The next time you `go build`, `go test`, or `go run` your project,
and detailed dependency version info will be added to your `go.mod` file
(or you can also run `go mod tidy` to do this directly).
This assumes you are using go modules with go 1.11+.
## Using a specific version
If you want to use a particular version of the `k8s.io/client-go` library,
you can indicate which version of `client-go` your project requires:
- If you are using Kubernetes versions >= `v1.17.0`, use a corresponding `v0.x.y` tag.
For example, `k8s.io/client-go@v0.20.4` corresponds to Kubernetes `v1.20.4`:
```sh
go get k8s.io/client-go@v0.20.4
```
- If you are using Kubernetes versions < `v1.17.0`, use a corresponding `kubernetes-1.x.y` tag.
For example, `k8s.io/client-go@kubernetes-1.16.3` corresponds to Kubernetes `v1.16.3`:
```sh
go get k8s.io/client-go@kubernetes-1.16.3
```
You can now import and use the `k8s.io/client-go` APIs in your project.
The next time you `go build`, `go test`, or `go run` your project,
`k8s.io/client-go` and its dependencies will be downloaded (if needed),
and detailed dependency version info will be added to your `go.mod` file
(or you can also run `go mod tidy` to do this directly).
## Troubleshooting
### Go versions prior to 1.16
If you get a message like
`module k8s.io/client-go@latest found (v1.5.2), but does not contain package k8s.io/client-go/...`,
you are likely using a go version prior to 1.16 and must explicitly specify the k8s.io/client-go version you want.
For example:
```sh
go get k8s.io/client-go@v0.20.4
```
### Conflicting requirements for older client-go versions
If you get a message like
`module k8s.io/api@latest found, but does not contain package k8s.io/api/auditregistration/v1alpha1`,
something in your build is likely requiring an old version of `k8s.io/client-go` like `v11.0.0+incompatible`.
First, try to fetch a more recent version. For example:
```sh
go get k8s.io/client-go@v0.20.4
```
If that doesn't resolve the problem, see what is requiring an `...+incompatible` version of client-go,
and update to use a newer version of that library, if possible:
```sh
go mod graph | grep " k8s.io/client-go@"
```
As a last resort, you can force the build to use a specific version of client-go,
even if some of your dependencies still want `...+incompatible` versions. For example:
```sh
go mod edit -replace=k8s.io/client-go=k8s.io/client-go@v0.20.4
go get k8s.io/client-go@v0.20.4
```
### Go modules disabled
If you get a message like `cannot use path@version syntax in GOPATH mode`,
see the instructions for [enabling go modules](#enabling-go-modules).
you likely do not have go modules enabled.
## Dependency management for the serious (or reluctant) user
Reasons why you might need to use a dependency management system:
* You use a dependency that client-go also uses, and don't want two copies of
the dependency compiled into your application. For some dependencies with
singletons or global inits (e.g. `glog`) this wouldn't even compile...
* You want to lock in a particular version (so you don't have to change your
code every time we change a public interface).
* You want your install to be reproducible. For example, for your CI system or
for new team members.
### Enabling go modules
Dependency management tools are built into go 1.11+ in the form of [go modules](https://github.com/golang/go/wiki/Modules).
These are used by the main Kubernetes repo (>= `v1.15.0`) and `client-go` (>= `kubernetes-1.15.0`) to manage dependencies.
Dependency management tools are built into go 1.11+ in the form of
[go modules](https://github.com/golang/go/wiki/Modules).
These are used by the main Kubernetes repo (>= `v1.15.0`) and
`client-go` (>= `kubernetes-1.15.0`) to manage dependencies.
If you are using go 1.11 or 1.12 and are working with a project located within `$GOPATH`,
you must opt into using go modules:
@ -49,33 +98,3 @@ If you do not already have one, `go mod init` will create one for you:
```sh
go mod init
```
### Add client-go as a dependency
Indicate which version of `client-go` your project requires:
- If you are using Kubernetes versions >= `v1.17.0`, use a corresponding
`v0.x.y` tag. For example, `k8s.io/client-go@v0.17.0` corresponds to Kubernetes `v1.17.0`:
```sh
go get k8s.io/client-go@v0.17.0
```
You can also use a non-semver `kubernetes-1.x.y` tag to refer to a version
of `client-go` corresponding to a given Kubernetes release. Prior to Kubernetes
`v1.17.0` these were the only tags available for use with go modules.
For example, `kubernetes-1.16.3` corresponds to Kubernetes `v1.16.3`.
However, it is recommended to use semver-like `v0.x.y` tags over non-semver
`kubernetes-1.x.y` tags to have a seamless experience with go modules.
- If you are using Kubernetes versions < `v1.17.0` (replace `kubernetes-1.16.3` with the desired version):
```sh
go get k8s.io/client-go@kubernetes-1.16.3
```
You can now import and use the `k8s.io/client-go` APIs in your project.
The next time you `go build`, `go test`, or `go run` your project,
`k8s.io/client-go` and its dependencies will be downloaded (if needed),
and detailed dependency version info will be added to your `go.mod` file
(or you can also run `go mod tidy` to do this directly).