From c8a8fb4177dbf3449684133f92bd065df8cb0419 Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Thu, 21 Mar 2019 23:33:40 -0400 Subject: [PATCH] Update client-go docs for modules - remove dep (c0a827dad6acc5fdea09967411aeeb9a8731d58f) - move godep to bottom (3308b07da50c9547bcbfa50297b9bb91a02e88a2) - bump example versions (9704cd1347ee287d388aa8f2b0091d4fe09640bb) - add go modules section (e37037f5ae7c862a4255465ef328b8a3b6db038a) - update go get docs (cda29fd9329a29856e5e3b218250b57ce8cbcd8f) --- staging/src/k8s.io/client-go/INSTALL.md | 164 ++++++++++++------------ 1 file changed, 79 insertions(+), 85 deletions(-) diff --git a/staging/src/k8s.io/client-go/INSTALL.md b/staging/src/k8s.io/client-go/INSTALL.md index 277fc2ffd09..9236f334a35 100644 --- a/staging/src/k8s.io/client-go/INSTALL.md +++ b/staging/src/k8s.io/client-go/INSTALL.md @@ -3,35 +3,48 @@ ## For the casual user 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: ```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` -includes most of its own dependencies in its `k8s.io/client-go/vendor` path, -except for `k8s.io/apimachinery` and `glog`. `go get` will recursively download -these excluded repos to your `$GOPATH`, if they don't already exist. If -`k8s.io/apimachinery` preexisted in `$GOPATH`, you also need to: +This will record a dependency on `k8s.io/client-go` in your go module. +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). + +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 +$ go get -u k8s.io/client-go/... $ 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 -apimachinery. +This downloads a version of `k8s.io/client-go` prior to v1.12.0, +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 prevent `go get` users from hitting issues like [#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, then you'll need to look down at the next section. 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, 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 for each follows. -### Godep +### Go modules -[godep](https://github.com/tools/godep) is an older dependency management tool, which is -used by the main Kubernetes repo and `client-go` 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 (>= 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 -$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`: +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: ```sh -go get k8s.io/client-go/... -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 ./... +export GO111MODULE=on ``` -At this point, `client-go`'s dependencies have been placed in your $GOPATH, but -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: +Ensure your project has a `go.mod` file defined at the root of your project. +If you do not already have one, `go mod init` will create one for you: ```sh -cd $GOPATH/src/ -godep save ./... +go mod init ``` -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. +Indicate which version of `client-go` your project requires. +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 @@ -99,7 +119,7 @@ your project: package: ( your project's import path ) # e.g. github.com/foo/bar import: - 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, @@ -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 import: - 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. - package: github.com/davecgh/go-spew 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) 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`, -you must opt into using go modules: +Before proceeding with the below instructions, you should ensure that your +$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 -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. -If you do not already have one, `go mod init` will create one for you: +At this point, `client-go`'s dependencies have been placed in your $GOPATH, but +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 -go mod init +cd $GOPATH/src/ +godep save ./... ``` -Indicate the matching versions of `k8s.io/client-go`, `k8s.io/api`, and `k8s.io/apimachinery` your project requires: - -```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`. +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.