Managing Stores

Page last updated:

A Store is a cluster level resource that provides a collection of buildpacks that can be utilized by Builders. Buildpacks are distributed and added to a store in buildpackages which are docker images containing one or more buildpacks.

Build Service ships with a curated collection of Tanzu buildpacks for Java, Nodejs, Go, PHP, nginx, and httpd and Paketo buildpacks for procfile, and .NET Core. Detailed documentation about the buildpacks that are installed with TBS can be found here. It is important to keep these buildpacks up-to-date. Updates to these buildpacks are provided on Tanzu Network.

In addition to supported Tanzu and Paketo buildpacks, custom buildpackages can be uploaded to Build Service stores.

The kp CLI can be used to manage clusterstores. The help text is published here.

$ kp clusterstore
ClusterStore Commands

Usage:
  kp clusterstore [command]

Aliases:
  clusterstore, clusterstores, clstrcsrs, clstrcsr, csrs, csr

Available Commands:
  add         Add buildpackage(s) to cluster store
  create      Create a cluster store
  delete      Delete a cluster store
  list        List cluster stores
  remove      Remove buildpackage(s) from cluster store
  save        Create or update a cluster store
  status      Display cluster store status

Flags:
  -h, --help   help for clusterstore

Note: These docs assume kp cli v0.3.* from TBS release v1.2.*. If a feature is not working, you may need to upgrade your cli.

Creating Buildpacks and Buildpackages

Documentation for creating buildpacks is available here.

Documentation for creating buildpackages is available here.

Note: Only Build Service Admins can perform store commands.

Listing ClusterStores

Users can view the existing stores with:

kp clusterstore list

Creating a ClusterStore

Tanzu Build Service ships with a default store containing all of the supported buildpacks. Users can create additional stores with:

kp clusterstore create <store-name> -b <buildpackage-1> -b <buildpackage-2>

Examples:

kp clusterstore create my-store -b my-registry.com/my-buildpackage
kp clusterstore create my-store -b my-registry.com/my-buildpackage -b my-registry.com/my-other-buildpackage
kp clusterstore create my-store -b ../path/to/my-local-buildpackage.cnb

Buildpackages will be uploaded to the registry used during installation.

Note: The user must have read access to the source Docker registry and write access to the registry used for installation on the local machine.

Saving a ClusterStore

Users can create or update a ClusterStore using the save command. The kp clusterstore save command is used exactly the same as kp clusterstore create, but it will determine if a clusterstore needs to be created or updated.

kp clusterstore save <store-name> -b <buildpackage-1> -b <buildpackage-2>

Adding Buildpackages to a ClusterStore

Users can add multiple buildpackages at a time from a registry or from a file on the local machine.

This command is useful for users that want to only consume certain buildpacks rather than update all dependencies with kp import.

  • If using a Docker registry:

    kp clusterstore add <store-name> -b <buildpackage-1> -b <buildpackage-2> ...
    

Note: The user must have read access to the source Docker registry and write access to the registry used for installation on the local machine.

  • If using local .cnb buildpackage files created as described in the buildpackages docs:

    kp clusterstore add <store-name> -b <path-to-buildpackage-1>.cnb -b <path-to-buildpackage-2>.cnb ...
    

Adding Buildpackages to a ClusterStore from Tanzu Network

Updated versions of all supported Buildpacks will be available on Tanzu Network as registry images. Updated Buildpacks will be found in the following locations:

Here is a list of how to update each buildpack that is included with Tanzu Build Service by default:

kp clusterstore add default registry.pivotal.io/tanzu-java-buildpack/java:<version>
kp clusterstore add default registry.pivotal.io/tanzu-nodejs-buildpack/nodejs:<version>
kp clusterstore add default registry.pivotal.io/tanzu-go-buildpack/go:<version>
kp clusterstore add default registry.pivotal.io/tbs-dependencies/paketo-buildpacks_dotnet-core:<version>
kp clusterstore add default registry.pivotal.io/tbs-dependencies/tanzu-buildpacks_php:<version>
kp clusterstore add default registry.pivotal.io/tbs-dependencies/tanzu-buildpacks_nginx:<version>
kp clusterstore add default registry.pivotal.io/tbs-dependencies/tanzu-buildpacks_httpd:<version>
kp clusterstore add default registry.pivotal.io/tbs-dependencies/paketo-buildpacks_procfile:<version>

Offline Adding Buildpackages to a ClusterStore from Tanzu Network

If your Tanzu Build Service installation is in an offline/air-gapped environment, you can update stores with the following offline workflow:

  1. Download the Dependency Descriptor file (descriptor-<version>.yaml) from the latest release on the Tanzu Build Service Dependencies page on Tanzu Network.

  2. Download the kp CLI for your operating system from the latest release on the Tanzu Build Service page.

  3. Download the kbld CLI for your operating system from the latest release on the kbld page.

  4. Download the dependency images for Tanzu Build Service to your local machine with kbld:

docker login registry.pivotal.io

kbld package -f descriptor-<version>.yaml \
  --output /tmp/packaged-dependencies.tar
  1. Move the output file packaged-dependencies.tar to a machine that has access to the “offline” environment

  2. Upload the dependency images to the registry used to deploy Tanzu Build Service:

docker login <build-service-registry>

kbld unpackage -f descriptor-<version>.yaml \
  --input /tmp/packaged-dependencies.tar \
  --repository <IMAGE-REPOSITORY> \
  --lock-output /tmp/dependencies-relocated.lock

Where IMAGE-REPOSITORY is the repository used to install Tanzu Build Service. This should be the same value as IMAGE-REPOSITORY used in the Installation Steps.

  1. Now that dependencies are relocated to the internal registry, you can use the following command to update the necessary resources:
kbld -f descriptor-<version>.yaml -f /tmp/dependencies-relocated.lock | kp import -f -

Removing Buildpackages from a ClusterStore

Users can remove a buildpackage from a ClusterStore by referencing the buildpackage Id and version.

kp clusterstore remove <store> -b <buildpackage-id>@<buildpackage-version>

Examples:

kp clusterstore remove my-store -b buildpackage@1.0.0
kp clusterstore remove my-store -b buildpackage@1.0.0 -b other-buildpackage@2.0.0

The ClusterStore status shows the list of buildpackage Id and version

Get ClusterStore Status

Users can use the kp CLI to get details about a store including buildpackages and their buildpacks, as well as meta-buildpacks. Meta-buildpacks are buildpacks that indicate the order that other buildpacks run:

To view the buildpackages in a store:

kp clusterstore status <store-name>

Example:

$kp clusterstore status default

Status:    Ready

BUILDPACKAGE ID                       VERSION    HOMEPAGE
paketo-buildpacks/go                  0.1.3      https://github.com/paketo-buildpacks/go
paketo-buildpacks/procfile            2.0.2      https://github.com/paketo-buildpacks/procfile
paketo-buildpacks/procfile            3.0.0      https://github.com/paketo-buildpacks/procfile
tanzu-buildpacks/dotnet-core          0.0.4
tanzu-buildpacks/dotnet-core          0.0.7
tanzu-buildpacks/dotnet-core          0.0.6
tanzu-buildpacks/go                   1.0.6
tanzu-buildpacks/go                   1.0.7
tanzu-buildpacks/go                   1.0.9
tanzu-buildpacks/go                   1.0.5
tanzu-buildpacks/httpd                0.0.38
tanzu-buildpacks/httpd                0.0.39
tanzu-buildpacks/httpd                0.0.40
tanzu-buildpacks/java                 3.8.0      https://github.com/pivotal-cf/tanzu-java
tanzu-buildpacks/java                 3.5.0      https://github.com/pivotal-cf/tanzu-java
tanzu-buildpacks/java                 4.1.0      https://github.com/pivotal-cf/tanzu-java
tanzu-buildpacks/java                 4.0.0      https://github.com/pivotal-cf/tanzu-java
tanzu-buildpacks/java-native-image    3.6.0      https://github.com/pivotal-cf/tanzu-java-native-image
tanzu-buildpacks/java-native-image    3.9.0      https://github.com/pivotal-cf/tanzu-java-native-image
tanzu-buildpacks/java-native-image    3.4.2      https://github.com/pivotal-cf/tanzu-java-native-image
tanzu-buildpacks/java-native-image    3.10.0     https://github.com/pivotal-cf/tanzu-java-native-image
tanzu-buildpacks/nginx                0.0.48
tanzu-buildpacks/nginx                0.0.46
tanzu-buildpacks/nodejs               1.1.0
tanzu-buildpacks/nodejs               1.2.3
tanzu-buildpacks/nodejs               1.2.2
tanzu-buildpacks/php                  0.0.3
tanzu-buildpacks/php                  0.0.5

To view buildpackages & their individual buildpacks as well as display the order of meta-buildpacks use the --verbose flag

kp clusterstore status <store-name> --verbose

Migrating Buildpacks

Build Service will never automatically remove buildpackages from the store unless you explicitly remove them. In this way, users can continue to use older buildpacks until the operator is ready to migrate them.

How you migrate is entirely dependent on the configuration of your Builder resources: * Builders that do not provide a buildpack version will automatically update to the latest buildpack version if it is available. * Builders that explicitly specify a buildpack version will not update automatically.

With the above in mind, migrating buildpackages in the store is as simple as kp clusterstore adding newer buildpackages and kp clusterstore removeing older buildpackages as necessary.

If you’d like fine-grained control over buildpack updates, you can create multiple stores to manage buildpack versions. Then, you can point individual builders at the desired store. Each store can be updated as needed without affecting other builders or fanning out large, sweeping changes.

Corresponding kpack Resource

All Build Service builders utilize cluster scoped Store Resources.