github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-23 11:50:44 +00:00
Code Issues Projects Releases Wiki Activity

Update client-go docs for modules

Browse Source 
- remove dep (c0a827dad6acc5fdea09967411aeeb9a8731d58f)
- move godep to bottom (3308b07da50c9547bcbfa50297b9bb91a02e88a2)
- bump example versions (9704cd1347ee287d388aa8f2b0091d4fe09640bb)
- add go modules section (e37037f5ae7c862a4255465ef328b8a3b6db038a)
- update go get docs (cda29fd9329a29856e5e3b218250b57ce8cbcd8f)
This commit is contained in:
Jordan Liggitt 2019-03-21 23:33:40 -04:00
parent 7cdd26e127
commit c8a8fb4177
1 changed files with 79 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
staging/src/k8s.io/client-go/INSTALL.md
View File

@ -3,35 +3,48 @@
## For the casual user ## For the casual user
If you want to write a simple script, don't care about a reproducible client 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 library install, don't mind getting HEAD (which may be less stable than a
particular release), then simply: particular release), then simply:
```sh ```sh
$ go get k8s.io/client-go/... $ go get k8s.io/client-go@master
``` ```
This will install `k8s.io/client-go` in your `$GOPATH`. `k8s.io/client-go` This will record a dependency on `k8s.io/client-go` in your go module.
includes most of its own dependencies in its `k8s.io/client-go/vendor` path, You can now import and use the `k8s.io/client-go` APIs in your project.
except for `k8s.io/apimachinery` and `glog`. `go get` will recursively download The next time you `go build`, `go test`, or `go run` your project,
these excluded repos to your `$GOPATH`, if they don't already exist. If `k8s.io/client-go` and its dependencies will be downloaded (if needed),
`k8s.io/apimachinery` preexisted in `$GOPATH`, you also need to: 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+.
If you get a message like `cannot use path@version syntax in GOPATH mode`,
you can choose to [opt into using go modules](#go-modules).
If you are using a version of go prior to 1.11, or do not wish to use
go modules, you can download `k8s.io/client-go` to your `$GOPATH` instead:
```sh ```sh
$ go get -u k8s.io/client-go/...
$ go get -u k8s.io/apimachinery/... $ go get -u k8s.io/apimachinery/...
$ cd $GOPATH/src/k8s.io/client-go
$ git checkout v11.0.0
$ cd $GOPATH/src/k8s.io/apimachinery
$ git checkout kubernetes-1.14.0
``` ```
because the head of client-go is only guaranteed to work with the head of This downloads a version of `k8s.io/client-go` prior to v1.12.0,
apimachinery. which includes most of its dependencies in its `k8s.io/client-go/vendor` path
(except for `k8s.io/apimachinery` and `glog`).
We excluded `k8s.io/apimachinery` and `glog` from `k8s.io/client-go/vendor` to We excluded `k8s.io/apimachinery` and `glog` from `k8s.io/client-go/vendor` to
prevent `go get` users from hitting issues like prevent `go get` users from hitting issues like
[#19](https://github.com/kubernetes/client-go/issues/19) and [#19](https://github.com/kubernetes/client-go/issues/19) and
[#83](https://github.com/kubernetes/client-go/issues/83). If your project share [#83](https://github.com/kubernetes/client-go/issues/83). If your project shares
other dependencies with client-go, and you hit issues similar to #19 or #83, other dependencies with client-go, and you hit issues similar to #19 or #83,
then you'll need to look down at the next section. then you'll need to look down at the next section.
Note: the official go policy is that libraries should not vendor their Note: the official go policy is that libraries should not vendor their
dependencies. This is unworkable for us, since our dependencies change and HEAD dependencies. This was unworkable for us, since our dependencies change and HEAD
on every dependency has not necessarily been tested with client-go. In fact, on every dependency has not necessarily been tested with client-go. In fact,
HEAD from all dependencies may not even compile with client-go! HEAD from all dependencies may not even compile with client-go!
@ -49,39 +62,46 @@ Reasons why you might need to use a dependency management system:
There are three tools you could in theory use for this. Instructions There are three tools you could in theory use for this. Instructions
for each follows. for each follows.
### Godep ### Go modules
[godep](https://github.com/tools/godep) is an older dependency management tool, which is Dependency management tools are built into go 1.11+ in the form of [go modules](https://github.com/golang/go/wiki/Modules).
used by the main Kubernetes repo and `client-go` to manage dependencies. These are used by the main Kubernetes repo (>= 1.15) and `client-go` (>= v12.0) to manage dependencies.
When using `client-go` v12.0.0+ and go 1.11.4+, go modules are the recommended dependency management tool.
Before proceeding with the below instructions, you should ensure that your If you are using go 1.11 or 1.12 and are working with a project located within `$GOPATH`,
$GOPATH is empty except for containing your own package and its dependencies, you must opt into using go modules:
and you have a copy of godep somewhere in your $PATH.
To install `client-go` and place its dependencies in your `$GOPATH`:
```sh ```sh
go get k8s.io/client-go/... export GO111MODULE=on
cd $GOPATH/src/k8s.io/client-go
git checkout v9.0.0 # replace v9.0.0 with the required version
# cd 1.5 # only necessary with 1.5 and 1.4 clients.
godep restore ./...
``` ```
At this point, `client-go`'s dependencies have been placed in your $GOPATH, but Ensure your project has a `go.mod` file defined at the root of your project.
if you were to build, `client-go` would still see its own copy of its If you do not already have one, `go mod init` will create one for you:
dependencies in its `vendor` directory. You have two options at this point.
If you would like to keep dependencies in your own project's vendor directory,
then you can continue like this:
```sh ```sh
cd $GOPATH/src/<my-pkg> go mod init
godep save ./...
``` ```
Alternatively, if you want to build using the dependencies in your `$GOPATH`, Indicate which version of `client-go` your project requires.
then `rm -rf vendor/` to remove `client-go`'s copy of its dependencies. For `client-go` 12.0.0+, this is a single step:
```sh
go get k8s.io/client-go@v12.0.0 # replace v12.0.0 with the required version
```
For `client-go` prior to v12.0.0, you also need to indicate the required versions of `k8s.io/api` and `k8s.io/apimachinery`:
```sh
go get k8s.io/client-go@v11.0.0 # replace v11.0.0 with the required version (or use kubernetes-1.x.y tags if desired)
go get k8s.io/api@kubernetes-1.14.0 # replace kubernetes-1.14.0 with the required version
go get k8s.io/apimachinery@kubernetes-1.14.0 # replace kubernetes-1.14.0 with the required version
```
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).
### Glide ### Glide
@ -99,7 +119,7 @@ your project:
package: ( your project's import path ) # e.g. github.com/foo/bar package: ( your project's import path ) # e.g. github.com/foo/bar
import: import:
- package: k8s.io/client-go - package: k8s.io/client-go
version: v9.0.0 # replace v9.0.0 with the required version version: v11.0.0 # replace v11.0.0 with the required version
``` ```
Second, add a Go file that imports `client-go` somewhere in your project, Second, add a Go file that imports `client-go` somewhere in your project,
@ -132,7 +152,7 @@ requests can override the version manually in `glide.yaml`. For example:
package: ( your project's import path ) # e.g. github.com/foo/bar package: ( your project's import path ) # e.g. github.com/foo/bar
import: import:
- package: k8s.io/client-go - package: k8s.io/client-go
version: v9.0.0 # replace v9.0.0 with the required version version: v11.0.0 # replace v11.0.0 with the required version
# Use a newer version of go-spew even though client-go wants an old one. # Use a newer version of go-spew even though client-go wants an old one.
- package: github.com/davecgh/go-spew - package: github.com/davecgh/go-spew
version: v1.1.0 version: v1.1.0
@ -143,62 +163,36 @@ After modifying, run `glide up -v` again to re-populate your /vendor directory.
Optionally, Glide users can also use [`glide-vc`](https://github.com/sgotti/glide-vc) Optionally, Glide users can also use [`glide-vc`](https://github.com/sgotti/glide-vc)
after running `glide up -v` to remove unused files from /vendor. after running `glide up -v` to remove unused files from /vendor.
### Go modules ### Godep
Dependency management tools are built into go 1.11+ in the form of [go modules](https://github.com/golang/go/wiki/Modules). [godep](https://github.com/tools/godep) is an older dependency management tool, which was
used by the main Kubernetes repo (<= 1.14) and `client-go` (<= v11.0) to manage dependencies.
If you are using go 1.11 or 1.12 and are working with a project located within `$GOPATH`, Before proceeding with the below instructions, you should ensure that your
you must opt into using go modules: $GOPATH is empty except for containing your own package and its dependencies,
and you have a copy of godep somewhere in your $PATH.
To install `client-go` and place its dependencies in your `$GOPATH`:
```sh ```sh
export GO111MODULE=on go get k8s.io/client-go/...
cd $GOPATH/src/k8s.io/client-go
git checkout v11.0.0 # v11.0.0 or older
# cd 1.5 # only necessary with 1.5 and 1.4 clients.
godep restore ./...
``` ```
Ensure your project has a `go.mod` file defined at the root of your project. At this point, `client-go`'s dependencies have been placed in your $GOPATH, but
If you do not already have one, `go mod init` will create one for you: if you were to build, `client-go` would still see its own copy of its
dependencies in its `vendor` directory. You have two options at this point.
If you would like to keep dependencies in your own project's vendor directory,
then you can continue like this:
```sh ```sh
go mod init cd $GOPATH/src/<my-pkg>
godep save ./...
``` ```
Indicate the matching versions of `k8s.io/client-go`, `k8s.io/api`, and `k8s.io/apimachinery` your project requires: Alternatively, if you want to build using the dependencies in your `$GOPATH`,
then `rm -rf vendor/` to remove `client-go`'s copy of its dependencies.
```sh
go get k8s.io/client-go@v10.0.0 # replace v10.0.0 with the required version (or use kubernetes-1.x.y tags if desired)
go get k8s.io/api@kubernetes-1.13.4 # replace kubernetes-1.13.4 with the required version
go get k8s.io/apimachinery@kubernetes-1.13.4 # replace kubernetes-1.13.4 with the required version
```
or you can edit your `go.mod` file directly to specify required versions:
```
require (
k8s.io/api kubernetes-1.13.4
k8s.io/apimachinery kubernetes-1.13.4
k8s.io/client-go v10.0.0
)
```
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.
You can also run `go mod tidy` to do this directly.
### Dep (Not supported yet!)
[dep](https://github.com/golang/dep) is an up-and-coming dependency management
tool, which has the goal of being accepted as part of the standard go toolchain.
However, client-go does **NOT** work well with `dep` yet. To support `dep`, we
need to fix at least two issues:
1. publish native `Gopkg.toml` in client-go and other k8s.io repos, like `k8s.io/apimachinery`;
2. find a way to express transitive constraints (see https://github.com/golang/dep/issues/1124).
As a workaround, which may or may not be worthwhile, you can specify all
client-go dependencies manually as
[override](https://github.com/golang/dep/blob/master/docs/Gopkg.toml.md#override)
in Gopkg.toml with the versions listed in [Godeps.json](./Godeps/Godeps.json),
and manually update them when you upgrade client-go version.
We are actively working on the two issues blocking using `dep`. For the
meantime, we recommend using `glide` or `godeps`.