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

Update client-go install instructions

Author: k8s-ci-robot

staging/src/k8s.io/client-go/INSTALL.md

@@ -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,65 +15,86 @@ 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+.
-If you get a message like `cannot use path@version syntax in GOPATH mode`,
-see the instructions for [enabling go modules](#enabling-go-modules).
+## Using a specific version
 
-## Dependency management for the serious (or reluctant) user
+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:
 
-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.
+- If you are using Kubernetes versions >= `v1.17.0`, use a corresponding `v0.x.y` tag.
+  For example, `k8s.io/[email protected]` corresponds to Kubernetes `v1.20.4`:
 
-### Enabling go modules
+```sh
+go get k8s.io/[email protected]
+```
 
-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:
+- If you are using Kubernetes versions < `v1.17.0`, use a corresponding `kubernetes-1.x.y` tag.
+  For example, `k8s.io/[email protected]` corresponds to Kubernetes `v1.16.3`:
 
 ```sh
-export GO111MODULE=on
+go get k8s.io/[email protected]
 ```
 
-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:
+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 mod init
+go get k8s.io/[email protected]
 ```
 
-### Add client-go as a dependency
+### Conflicting requirements for older client-go versions
 
-Indicate which version of `client-go` your project requires:
+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`.
 
-- If you are using Kubernetes versions >= `v1.17.0`, use a corresponding
-`v0.x.y` tag. For example, `k8s.io/[email protected]` corresponds to Kubernetes `v1.17.0`:
+First, try to fetch a more recent version. For example:
+```sh
+go get k8s.io/[email protected]
+```
 
+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 get k8s.io/client-go@v0.17.0
+go mod graph | grep " k8s.io/client-go@"
 ```
 
-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.
+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/[email protected]
+go get k8s.io/[email protected]
+```
+
+### Go modules disabled
 
-- If you are using Kubernetes versions < `v1.17.0` (replace `kubernetes-1.16.3` with the desired version):
+If you get a message like `cannot use path@version syntax in GOPATH mode`,
+you likely do not have go modules enabled.
+
+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:
 
 ```sh
-go get k8s.io/[email protected]
+export GO111MODULE=on
 ```
 
-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).
+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
+go mod init
+```