Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.

Dependency Management

Kubebuilder uses dep to manage dependencies. Different dependency management tasks can be done using the dep ensure command.

Adding new dependencies

Kubernetes Dependencies

Kubebuilder-generated projects depends on a number of Kubernetes dependencies internally. Kubebuilder (using the controller-runtime library) makes sure that the parts of these dependencies that are exposed in the Kubebuilder API remain stable.

It's recommended not to make use of most of these libraries directly, since they change frequently in incompatible ways. The k8s.io/api repository is the exception to this, and it's reccomended that you rely on the version that kubebuilder requires, instead of listing it as a direct dependency in Gopkg.toml.

However, if you do add direct dependencies on any of these libraries yourself, be aware that you may encounter dependency conflicts. See the problem with kubernetes libraries below for more information.

Dep manages dependency constraints using the Gopkg.toml file. You can add new dependencies by adding new [[constraint]] stanzas to that file. Alternatively, if you're not using kubebuilder update, you can use the dep ensure -add command to add new dependencies to your Gopkg.toml.

# edit Gopkg.toml OR perform the following:
dep ensure -add github.com/pkg/errors

Updating existing dependencies

Update dependencies for your project to the latest minor and patch versions.

dep ensure -update sigs.k8s.io/controller-runtime sigs.k8s.io/controller-tools

Repopulating your vendor directory

Dependency source code is stored in the vendor directory. If it ever gets deleted, you can repopulate it using the exact dependency versions stored in Gopkg.lock.

dep ensure

How Kubebuilder's Dependencies Work

Under the Hood

The information in this section details how Kubebuilder's dependency graph works. It's not necessary for day-to-day use of Kubebuilder, but can be useful if you want to understand how a particular version of Kubebuilder relates to a particular version of Kubernetes.

TL;DR

As of Kubebuilder 1.0.2:

  • Projects generated with Kubebuilder list a semantic version of controller-runtime and controller-tools as their only direct dependencies. All other Kubernetes-related libraries are transative dependencies.

  • controller-runtime and controller-tools each list a specific, identical set of dependencies on Kubernetes libraries and related libraries.

  • Once you've updated your dependencies with kubebuilder update vendor, you'll be able to run dep ensure and dep ensure --update sigs.k8s.io/controller-runtime sigs.k8s.io/controller-tools to safely update all your dependencies in the future.

  • You can depend on controller-runtime to follow semantic versioning guarantees -- we won't break your code without introducing a new major version, for both the interfaces in controller-runtime, and the bits of the kubernetes libraries that controller-runtime actually exposes.

The Problem with Kubernetes libraries

The kubernetes project exports a collection of libraries (which we'll call the k8s-deps from now on) that expose common functionality used when building applications that consume Kubernetes APIs (e.g. clients, informers, etc). Due to the way Kubrenetes is versioned (non-semantically), all of these dependencies must closely match -- differing versions can cause strange compilation or runtime errors.

Beyond this, these libraries have their own set of dependencies which are not always the latest versions, or are occaisionally in-between versions.

Collecting the correct set of dependencies for any given Kubernetes project can thus be tricky.

Using Prebaked Manifests (Kubebuilder pre-1.0.2)

Before version 1.0.2, Kubebuilder shipped a pre-baked manifest of the correct dependencies. When scaffolding out at new project using kubebuilder init (a kb-project), it would copy over a Gopkg.toml file containing the exact dependency versions required for the project (which could then be used by dep dependency management tool to actually fetch the dependencies).

In addition to the Kubernetes dependencies required, this also specified that all kb-projects use the master branch of the controller-runtime library, which provides the abstractions that Kubebuilder is built upon. Because controller-runtime wraps and consumes Kubernetes, it also needs specific versions of the k8s-deps, and those version must match the ones listed in the kb-project's Gopkg.toml, otherwise we'd have conflicting dependencies.

The Problem with Prebaked Manifests

Using the master branch as the target version of controller-runtime made it impossible to make breaking changes to controller-runtime. However, even when using a specific version of controller-runtime, it's still difficult to make changes.

Since kb-projects must use an identical set of dependencies to controller-runtime, any update to the controller-runtime dependencies (say, to pull in a new feature) would have caused immediate dependency version conflicts. Effectively, any update to the dependencies had to be treated as a major version revision, and there would have been no way to tell the difference between "this release includes breaking API changes" and "this release simply switches to a newer version of the k8s-deps".

Transitive Dependencies (Kubebuilder 1.0.2+)

As noted above, any dependency version in kb-projects must match dependency versions listed in controller-runtime, exactly. Furthermore, it turns out, by design, the set of k8s-deps used in controller-runtime is a superset of the set of dependencies actually imported by kb-projects.

Therefore, in kb-projects generated with Kubebuilder 1.0.2+, no dependencies are listed besides controller-runtime (and controller-tools). All of the k8s-deps become transitive dependencies, whose versions are determined when dep (the dependency management tool) looks at the versions required by controller-runtime.

controller-runtime is semantically versioned, so any changes to either the interfaces in controller-runtime, or the pieces of the k8s-deps that are exposed as part of those interfaces, means a new major version of controller-runtime will be released. Any other changes (new features, bug fixes, updates to k8s-deps which don't break interfaces) yield minor or patch versions (as per semver), which can easily and safely be updated to by kb-projects.

controller-tools Dependencies

controller-tools is the library used to generate CRD and RBAC manifests for kb-projects. With Kubebuilder 1.0.2+, it does not directly depend on controller-runtime, but shares the same set of dependencies. It therefore must be updated in lockstep with controller-runtime. This is mostly a concern of the controller-tools/controller-runtime maintainers, and will not affect users. Like controller-runtime, controller-tools uses semver.