Getting Started with Tanzu Build Service

Page last updated:

This topic describes how to get started with a typical installation of Tanzu Build Service and create an Image.

This page is meant to serve as a quick-start guide and may not include some configurations required for your specific environment. For more details on installation, see Installing Tanzu Build Service.


Before you install Build Service, you must:

  • Have access to the Kubernetes cluster satisfying the minimum required permissions.

  • Ensure your Kubernetes cluster is configured with default StorageClass. Tanzu Build Service will default to using 2G of cache if a default StorageClass is defined. Build Service utilizes PersistentVolumeClaims to cache build artifacts, which reduces the time of subsequent builds.

    For more information, see Persistent Volumes in the Kubernetes documentation. And for information on defining a default StorageClass, see Changing the default StorageClass

  • Download three Carvel CLIs for your operating system. These tools will facilitate the installation of Tanzu Build Service on your cluster. They can be found on their respective Tanzu Network pages:

    • kapp is a deployment tool that allows users to manage Kubernetes resources in bulk.
    • ytt is a templating tool that understands YAML structure.
    • kbld is needed to map relocated images to k8s config.
    • imgpkg is tool that relocates container images and pulls the release configuration files.
  • Find the latest Tanzu Build Service version by checking the Tanzu Build Service page on Tanzu Network. Just knowing the version is sufficient.

  • Download the kp CLI for your operating system from the Tanzu Build Service page on Tanzu Network. The kp CLI help text is published here.

    • 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.
  • Download the docker cli to authenticate with registries.

  • Download the Dependency Descriptor file (descriptor-<version>.yaml) from the latest release on the Tanzu Build Service Dependencies page on Tanzu Network. This file contains paths to images that contain dependency resources Tanzu Build Service needs to execute image builds.


For this example setup, we will make the following assumptions:

  • You are installing TBS 1.2.1 (This is the latest version at the time of writing. Go to the Tanzu Build Service page to find the most up-to-date version).
  • You are using a registry named with credentials
    • Username: my-user
    • Password: my-password
  • Your registry uses a self-signed CA certificate and you have access to the cert in a file /tmp/ca.crt
    • The nodes on your cluster must also be configured to trust this CA certificate so they can pull in images. Configuration for this depends on the cluster provider
  • You are using an “online” environment that has access to the internet


Relocate Images to a Registry

This procedure relocates images from the Tanzu Network registry to your registry.

  1. Log in to your image registry:
docker login --tlscacert /tmp/ca.crt
  1. Log in to the Tanzu Network registry with your Tanzu Network credentials:
docker login
  1. Relocate the images with the Carvel tool imgpkg by running:
imgpkg copy -b "" --to-repo --registry-ca-cert-path /tmp/ca.crt
  1. Pull the Tanzu Build Service bundle locally using imgpkg:
imgpkg pull -b "" -o /tmp/bundle

Install Tanzu Build Service

Use the Carvel tools kapp, ytt, and kbld to install Build Service and define the required Build Service parameters by running:

ytt -f /tmp/bundle/values.yaml \
    -f /tmp/bundle/config/ \
    -f /tmp/ca.crt \
    -v docker_repository='' \
    -v docker_username='my-user' \
    -v docker_password='my-password' \
    | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
    | kapp deploy -a tanzu-build-service -f- -y

Import Tanzu Build Service Dependencies

The Tanzu Build Service Dependencies (Stacks, Buildpacks, Builders, etc.) are used to build applications and keep them patched.

These must be imported with the kp cli and the Dependency Descriptor (descriptor-<version>.yaml) file from the Tanzu Build Service Dependencies page:

kp import -f /tmp/descriptor-<version>.yaml --registry-ca-cert-path /tmp/ca.crt

Successfully performing a kp import command requires that your Tanzu Network account has access to the images specified in the Dependency Descriptor file. Users can only access these images if they agree to the dependency EULAs.

Users must navigate to the following dependencies pages in Tanzu Network and accept all EULAs highlighted in yellow.

  1. Tanzu Build Service Dependencies
  2. Buildpacks for VMware Tanzu
  3. Stacks for VMware Tanzu

Note: `kp import` will fail if it cannot access the images in all of the above Tanzu Network pages.

Verify Installation

To verify your Build Service installation:

List the cluster builders available in your installation:

kp clusterbuilder list

You should see an output that looks as follows:

NAME       READY    STACK                          IMAGE
base       true     io.buildpacks.stacks.bionic    <image@sha256:digest>
default    true     io.buildpacks.stacks.bionic    <image@sha256:digest>
full       true     io.buildpacks.stacks.bionic    <image@sha256:digest>
tiny       true     io.paketo.stacks.tiny          <image@sha256:digest>

Create an Image

You can now create a Tanzu Build Service Image to start building you app and keep it patched with the latest Stack and Buildpack Dependencies.

We will assume you are using the default namespace, use -n when using kp to set a specific namespace.

  1. Create a Kubernetes Secret that will allow your Builds to push to the desired registry with the kp cli:
kp secret create my-registry-creds --registry --registry-user my-user

You will be prompted for your password (my-password).

  1. Create the Tanzu Build Service Image:

We will use a sample java-maven app:

kp image create my-image --tag --git --sub-path ./apps/java-maven --wait