Version management

Maintain different package versions within the same ksonnet application

The team behind ksonnet is stepping back from the project. As a result, work on ksonnet will end and the GitHub repositories will be archived. You can read more about our decision here.


A registry is a repository of packages in ksonnet. Since a registry can be pushed to GitHub, versioning is supported for packages when installed in a ksonnet application.

Packages with different versions can exist in a ksonnet application. This offers a lot of flexibility behind installing packages while minimizing the number of registries needed.


In ksonnet 0.11 and below, versioning of registries were tracked by the deprecated --version flag. Current versions of ksonnet tracks versioning for each package.

Users may see this warning when there are packages without versions because the registry was initialized on an older version of ksonnet:

WARN[0000] Versioned packages stored in unversioned paths - please run `ks upgrade` to correct

Change package versions

When installing a package, ksonnet will automatically look for the package corresponding to the branch name in the registry URI.

The package version can be specific by passing a branch name or a SHA-1 value for a GitHub repository.

# No version explicity referenced
$ ks pkg install incubator/nginx

# Version as a GitHub branch or tag
$ ks pkg install incubator/nginx@test-reg

# Specify a long or short SHA-1 value
$ ks pkg install incubator/nginx@be6b9e6df33a56423e7b02d03fae783d3a456b44
$ ks pkg install incubator/nginx@be6b9e6

# SemVer as the version with Helm registries
$ ks pkg install helm-stable/redis@3.4.1

Generate components from versioned packages

Multiple versions of a package can exist in a ksonnet application within vendor/.

When generating components, ksonnet will use the most recently installed package. For example, the test-reg branch does not have descriptions for the nginx prototypes. If incubator/nginx is installed as a package followed by installing incubator/nginx@test-reg,

Listing the prototypes should show empty descriptions for io.ksonnet.pkg.nginx-server-block and io.ksonnet.pkg.nginx-simple. To use the package from master, install incubator/nginx once again.

$ ks pkg install incubator/nginx
$ ks pkg install incubator/nginx@test-reg
$ ks prototype list

# Component from test-reg is used
$ ks generate nginx-simple nginx
Last updated on: September 4, 2018