Vendoring Client-Go and Dependency Management

- [k8s.io/sample-apiserver](https://github.com/kubernetes/sample-apiserver) is a simple user-provided API server that is integrated into a cluster via [API aggregation](/docs/concepts/api-extension/apiserver-aggregation/). - [k8s.io/sample-controller](https://github.com/kubernetes/sample-controller) is a full-featured [controller](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/controllers.md) (also called an operator) with shared informers and a workqueue to process created, changed or deleted objects. It is based on CustomResourceDefinitions and uses [k8s.io/code-generator](https://github.com/kubernetes/code-generator) to generate deepcopy functions, typed clientsets, informers, and listers. ## Vendoring In order to update from the previous version 5 to version 6 of client-go, the library itself as well as certain third-party dependencies must be updated. Previously, this process had been tedious due to the fact that a lot of code got refactored or relocated within the existing package layout across releases. Fortunately, far less code had to move in the latest version, which should ease the upgrade procedure for most users. ### State of the published repositories In the past [k8s.io/client-go](https://github.com/kubernetes/client-go), [k8s.io/api](https://github.com/kubernetes/api), and [k8s.io/apimachinery](https://github.com/kubernetes/apimachinery) were updated infrequently. Tags (for example, v4.0.0) were created quite some time after the Kubernetes releases. With the 1.9 release we resumed running a nightly bot that updates all the repositories for public consumption, even before manual tagging. This includes the branches: - master - release-1.8 / release-5.0 - release-1.9 / release-6.0 Kubernetes tags (for example, v1.9.1-beta1) are also applied automatically to the published repositories, prefixed with kubernetes- (for example, kubernetes-1.9.1-beta1). These tags have limited test coverage, but can be used by early adopters of client-go and the other libraries. Moreover, they help to vendor the correct version of [k8s.io/api](https://github.com/kubernetes/api) and [k8s.io/apimachinery](https://github.com/kubernetes/apimachinery). Note that we only create a v6.0.3-like semantic versioning tag on [k8s.io/client-go](https://github.com/kubernetes/client-go). The corresponding tag for k8s.io/api and k8s.io/apimachinery is kubernetes-1.9.3. Also note that only these tags correspond to tested releases of Kubernetes. If you depend on the release branch, e.g., release-1.9, your client is running on unreleased Kubernetes code. ### State of vendoring of client-go In general, the list of which dependencies to vendor is automatically generated and written to the file Godeps/Godeps.json. Only the revisions listed there are tested. This means especially that we do not and cannot test the code-base against master branches of our dependencies. This puts us in the following situation depending on the used vendoring tool: - [godep](https://github.com/tools/godep) reads Godeps/Godeps.json by running godep restore from k8s.io/client-go in your GOPATH. Then use godep save to vendor in your project. godep will choose the correct versions from your GOPATH. - [glide](https://github.com/Masterminds/glide) reads Godeps/Godeps.json automatically from its dependencies including from k8s.io/client-go, both on init and on update. Hence, glide should be mostly automatic as long as there are no conflicts. - [dep](https://github.com/golang/dep) does not currently respect Godeps/Godeps.json in a consistent way, especially not on updates. It is crucial to specify client-go dependencies manually as constraints or overrides, also for non k8s.io/\* dependencies. Without those, dep simply chooses the dependency master branches, which can cause problems as they are updated frequently. - The Kubernetes and golang/dep community are aware of the problems [[issue #1124](https://github.com/golang/dep/issues/1124), [issue #1236](https://github.com/golang/dep/issues/1236)] and [are working together on solutions](https://github.com/kubernetes-dep-experiment/client-go). Until then special care must be taken.

This section discusses vendoring client-go, the update frequency of k8s.io/client-go, k8s.io/api, and k8s.io/apimachinery repositories, and the impact of nightly bots. It details how different vendoring tools like godep, glide, and dep handle dependencies, emphasizing the importance of specifying client-go dependencies manually as constraints or overrides when using dep to avoid issues with master branches.