1# Installing client-go 2 3## For the casual user 4 5If you want to write a simple script, don't care about a reproducible client 6library install, don't mind getting HEAD (which may be less stable than a 7particular release), then simply: 8 9```sh 10go get k8s.io/client-go@master 11``` 12 13This will record a dependency on `k8s.io/client-go` in your go module. 14You can now import and use the `k8s.io/client-go` APIs in your project. 15The next time you `go build`, `go test`, or `go run` your project, 16`k8s.io/client-go` and its dependencies will be downloaded (if needed), 17and detailed dependency version info will be added to your `go.mod` file 18(or you can also run `go mod tidy` to do this directly). 19 20This assumes you are using go modules with go 1.11+. 21If you get a message like `cannot use path@version syntax in GOPATH mode`, 22you can choose to [opt into using go modules](#go-modules). 23If you are using a version of go prior to 1.11, or do not wish to use 24go modules, you can download `k8s.io/client-go` to your `$GOPATH` instead: 25 26```sh 27go get -u k8s.io/client-go/... 28go get -u k8s.io/apimachinery/... 29cd $GOPATH/src/k8s.io/client-go 30git checkout v11.0.0 31cd $GOPATH/src/k8s.io/apimachinery 32git checkout kubernetes-1.14.0 33``` 34 35This downloads a version of `k8s.io/client-go` prior to v1.12.0, 36which includes most of its dependencies in its `k8s.io/client-go/vendor` path 37(except for `k8s.io/apimachinery` and `glog`). 38 39We excluded `k8s.io/apimachinery` and `glog` from `k8s.io/client-go/vendor` to 40prevent `go get` users from hitting issues like 41[#19](https://github.com/kubernetes/client-go/issues/19) and 42[#83](https://github.com/kubernetes/client-go/issues/83). If your project shares 43other dependencies with client-go, and you hit issues similar to #19 or #83, 44then you'll need to look down at the next section. 45 46Note: the official go policy is that libraries should not vendor their 47dependencies. This was unworkable for us, since our dependencies change and HEAD 48on every dependency has not necessarily been tested with client-go. In fact, 49HEAD from all dependencies may not even compile with client-go! 50 51## Dependency management for the serious (or reluctant) user 52 53Reasons why you might need to use a dependency management system: 54* You use a dependency that client-go also uses, and don't want two copies of 55 the dependency compiled into your application. For some dependencies with 56 singletons or global inits (e.g. `glog`) this wouldn't even compile... 57* You want to lock in a particular version (so you don't have to change your 58 code every time we change a public interface). 59* You want your install to be reproducible. For example, for your CI system or 60 for new team members. 61 62There are three tools you could in theory use for this. Instructions 63for each follows. 64 65### Go modules 66 67Dependency management tools are built into go 1.11+ in the form of [go modules](https://github.com/golang/go/wiki/Modules). 68These are used by the main Kubernetes repo (>= 1.15) and `client-go` (on master, and v12.0.0+ once released) to manage dependencies. 69When using `client-go` v12.0.0+ and go 1.11.4+, go modules are the recommended dependency management tool. 70 71If you are using go 1.11 or 1.12 and are working with a project located within `$GOPATH`, 72you must opt into using go modules: 73 74```sh 75export GO111MODULE=on 76``` 77 78Ensure your project has a `go.mod` file defined at the root of your project. 79If you do not already have one, `go mod init` will create one for you: 80 81```sh 82go mod init 83``` 84 85Indicate which version of `client-go` your project requires. 86For `client-go` on master (and once version v12.0.0 is released), this is a single step: 87 88```sh 89go get k8s.io/client-go@master # or v12.0.0+ once released 90``` 91 92For `client-go` prior to v12.0.0, you also need to indicate the required versions of `k8s.io/api` and `k8s.io/apimachinery`: 93 94```sh 95go 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) 96go get k8s.io/api@kubernetes-1.14.0 # replace kubernetes-1.14.0 with the required version 97go get k8s.io/apimachinery@kubernetes-1.14.0 # replace kubernetes-1.14.0 with the required version 98``` 99 100You can now import and use the `k8s.io/client-go` APIs in your project. 101The next time you `go build`, `go test`, or `go run` your project, 102`k8s.io/client-go` and its dependencies will be downloaded (if needed), 103and detailed dependency version info will be added to your `go.mod` file 104(or you can also run `go mod tidy` to do this directly). 105 106### Glide 107 108[Glide](https://github.com/Masterminds/glide) is another popular dependency 109management tool for Go. Glide will manage your /vendor directory, but unlike 110godep, will not use or modify your $GOPATH (there's no equivalent of 111`godep restore` or `godep save`). 112 113Generally, it's best to avoid Glide's many subcommands, favoring modifying 114Glide's manifest file (`glide.yaml`) directly, then running 115`glide update --strip-vendor`. First create a `glide.yaml` file at the root of 116your project: 117 118```yaml 119package: ( your project's import path ) # e.g. github.com/foo/bar 120import: 121- package: k8s.io/client-go 122 version: v11.0.0 # replace v11.0.0 with the required version 123``` 124 125Second, add a Go file that imports `client-go` somewhere in your project, 126otherwise `client-go`'s dependencies will not be added to your project's 127vendor/. Then run the following command in the same directory as `glide.yaml`: 128 129```sh 130glide update --strip-vendor 131``` 132 133This can also be abbreviated as: 134 135```sh 136glide up -v 137``` 138 139At this point, `k8s.io/client-go` should be added to your project's vendor/. 140`client-go`'s dependencies should be flattened and be added to your project's 141vendor/ as well. 142 143Glide will detect the versions of dependencies `client-go` specified in 144`client-go`'s Godep.json file, and automatically set the versions of these 145imports in your /vendor directory. It will also record the detected version of 146all dependencies in the `glide.lock` file. 147 148Projects that require a different version of a dependency than `client-go` 149requests can override the version manually in `glide.yaml`. For example: 150 151```yaml 152package: ( your project's import path ) # e.g. github.com/foo/bar 153import: 154- package: k8s.io/client-go 155 version: v11.0.0 # replace v11.0.0 with the required version 156# Use a newer version of go-spew even though client-go wants an old one. 157- package: github.com/davecgh/go-spew 158 version: v1.1.0 159``` 160 161After modifying, run `glide up -v` again to re-populate your /vendor directory. 162 163Optionally, Glide users can also use [`glide-vc`](https://github.com/sgotti/glide-vc) 164after running `glide up -v` to remove unused files from /vendor. 165 166### Godep 167 168[godep](https://github.com/tools/godep) is an older dependency management tool, which was 169used by the main Kubernetes repo (<= 1.14) and `client-go` (<= v11.0) to manage dependencies. 170 171Before proceeding with the below instructions, you should ensure that your 172$GOPATH is empty except for containing your own package and its dependencies, 173and you have a copy of godep somewhere in your $PATH. 174 175To install `client-go` and place its dependencies in your `$GOPATH`: 176 177```sh 178go get k8s.io/client-go/... 179cd $GOPATH/src/k8s.io/client-go 180git checkout v11.0.0 # v11.0.0 or older 181# cd 1.5 # only necessary with 1.5 and 1.4 clients. 182godep restore ./... 183``` 184 185At this point, `client-go`'s dependencies have been placed in your $GOPATH, but 186if you were to build, `client-go` would still see its own copy of its 187dependencies in its `vendor` directory. You have two options at this point. 188 189If you would like to keep dependencies in your own project's vendor directory, 190then you can continue like this: 191 192```sh 193cd $GOPATH/src/<my-pkg> 194godep save ./... 195``` 196 197Alternatively, if you want to build using the dependencies in your `$GOPATH`, 198then `rm -rf vendor/` to remove `client-go`'s copy of its dependencies. 199