Getting Started with Tanzu Build Service

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.

Prerequisites

Before you install Build Service, you must:

Have access to the Kubernetes cluster satisfying the minimum required permissions.
Users must navigate to the following dependencies pages in Tanzu Network and accept all EULAs highlighted in yellow.
Ensure your Kubernetes cluster is configured with default StorageClass. Tanzu Build Service defaults 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 the Carvel CLI tools for your operating system. These tools will facilitate the installation of Tanzu Build Service on your cluster. They can be found on Tanzu Network under the Tanzu Cluster Essentials page. The download comes with four binaries that you will use:
- kapp is a deployment tool that allows users to manage Kubernetes resources in bulk.
- ytt is a templating tool that understands YAML structure. Version 0.35.0 or higher is required.
- kbld is needed to map relocated images to k8s config.
- imgpkg is tool that relocates container images and pulls the release configuration files. Version 0.12.0 or higher is required.
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 you are using kp CLI v0.9.x with Tanzu Build Service v1.7.x. If a feature is not working, you might need to upgrade your CLI.
Download either the docker CLI or crane CLI for authentication with registries.

Assumptions

For this example setup, we make the following assumptions:

You are installing TBS 1.9.0 (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 my.registry.io 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

Deprecated Features

The (legacy) CNB BOM format is deprecated, but enabled by default in TBS. Support can be deactivated manually by passing --data-value-yaml include_legacy_bom=false to ytt when processing the TBS bundle or by adding include_legacy_bom=false to your tbs-values.yml file.

Installation

Relocate Images to a Registry

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

If using the docker CLI, run:

docker login my.registry.io --tlscacert /tmp/ca.crt

If using the crane CLI, run:

crane auth login my.registry.io --tlscacert /tmp/ca.crt

Log in to the Tanzu Network registry with your Tanzu Network credentials:
- If using the docker CLI, run:
```
docker login registry.tanzu.vmware.com
```
- If using the crane CLI, run:
```
crane auth login registry.tanzu.vmware.com
```

Relocate the images with the Carvel tool imgpkg by running:

imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:1.9.0" --to-repo my.registry.io/some-repo/tbs --registry-ca-cert-path /tmp/ca.crt

Pull the Tanzu Build Service bundle locally using imgpkg:

imgpkg pull -b "my.registry.io/tbs:1.9.0" -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/config/ \
  -f /tmp/ca.crt \
  -v kp_default_repository='my.registry.io/tbs' \
  -v kp_default_repository_username='my-user' \
  -v kp_default_repository_password='my-password' \
  --data-value-yaml pull_from_kp_default_repo=true \
  -v tanzunet_username='tanzunet-username' \
  -v tanzunet_password='tanzunet-password' \
  -v descriptor_name='lite' \
  --data-value-yaml enable_automatic_dependency_updates=true \
  | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
  | kapp deploy -a tanzu-build-service -f- -y

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 assume you are using the default namespace, use -n when using kp to set a specific namespace.

Create a Kubernetes Secret that allows your Builds to push to the desired registry with the kp cli:
```
kp secret create my-registry-creds --registry my.registry.io --registry-user my-user
```
You are prompted for your password (my-password).

Create the Tanzu Build Service Image:

We use a sample java-maven app:

kp image create my-image --tag my.registry.io/tbs/test-app --git https://github.com/buildpacks/samples --sub-path ./apps/java-maven --wait