Install Tanzu Build Service by using a profile (recommended)

This topic tells you how to install and configure Tanzu Build Service (commonly known as TBS) by using a profile.

VMware recommends installing Tanzu Build Service with the Tanzu CLI and kapp controller through the Tanzu Application Platform buildservice install profile.

To view the previous methods of installation, see Installing without kapp controller and Installing with kapp controller.

Prerequisites

Have a Kubernetes cluster v1.23 or later.
Ensure that all worker nodes have at least 50 GB of ephemeral storage allocated to them.
- To do this on vSphere with Tanzu, mount a 50 GB volume at /var/lib/containerd to the worker nodes in the TanzuKubernetesCluster resource that corresponds to your vSphere with Tanzu cluster. For information about configuring storage on worker nodes, see the VMware vSphere documentation.
Have access to a container image registry to install Tanzu Build Service and store application images.
- Although the documentation references specific registries for the purpose of providing examples, any registry that adheres to the Docker Registry HTTP API V2 is supported.
- If installing using the lite dependencies, VMware recommends at least 1 GB of registry storage.
- If installing using the full dependencies, which you can use in offline environments, VMware recommends at least 10 GB of available storage.
- This registry space suggestion does not include the space used for application images built by Tanzu Build Service.
Ensure that your Kubernetes cluster is configured with a default StorageClass. If a default StorageClass is defined, 2 GB of cache is the default. PersistentVolumeClaims caches build artifacts, which reduces the time of subsequent builds.
- For more information about persistent volumes see the Kubernetes documentation.
- For information about defining a default StorageClass, see the Kubernetes documentation.

Accept Required Eulas

Navigate to the following pages in VMware Tanzu Network and accept all EULAs highlighted in yellow.
- Tanzu Application Platform
- Tanzu Cluster Essentials
To use the Automatic Dependency Updater, accept the following:

Install Required Software

Install the Tanzu CLI by following the instructions in Install Tanzu CLI in the Tanzu Application Platform documentation.
Install Cluster Essentials by following the instructions in Deploying Cluster Essentials in the Cluster Essentials documentation.

Note: When you use a VMware Tanzu Kubernetes Grid cluster, you do not need to install Cluster Essentials because the contents of Cluster Essentials are already installed on your cluster.
Install the kp CLI for your operating system from the VMware Tanzu Network. This installation procedure requires kp CLI v0.10.x with Tanzu Build Service v1.10.x.
Install either the Docker CLI or crane CLI for authentication with registries.
Install the Carvel imgpkg CLI.

Set Up Registry Credentials

Log in to your image registry by running:
```
docker login MY-REGISTRY
```
Where MY-REGISTRY is your own registry.
Log in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:
```
docker login registry.tanzu.vmware.com
```

Relocate images to a registry

To query for the available versions of Tanzu Application Platform on VMware Tanzu Network Registry, run:

imgpkg tag list -i registry.tanzu.vmware.com/tanzu-application-platform/tap-packages | grep -v sha | sort -V

Set up environment variables for installation use by running:
```
export INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER
export INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD
export INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY
export TAP_VERSION=VERSION-NUMBER
export INSTALL_REPO=TARGET-REPOSITORY
```
Where:
- MY-REGISTRY-USER is the user with write access to MY-REGISTRY.
- MY-REGISTRY-PASSWORD is the password for MY-REGISTRY-USER.
- MY-REGISTRY is your own registry.
- VERSION-NUMBER is the Tanzu Application Platform version. NOTE: To find the latest version, see VMware Tanzu Network.
- TARGET-REPOSITORY is your target repository, a directory or repository on MY-REGISTRY that serves as the location for the installation files for Tanzu Application Platform.
VMware recommends using a JSON key file to authenticate with Google Container Registry. In this case, the value of INSTALL_REGISTRY_USERNAME is _json_key and the value of INSTALL_REGISTRY_PASSWORD is the content of the JSON key file. For more information about how to generate the JSON key file, see Google Container Registry documentation.

Relocate the images with the imgpkg CLI by running:

Non-Air-gapped Environments:

imgpkg copy -b registry.tanzu.vmware.com/tanzu-application-platform/tap-packages:${TAP_VERSION} --to-repo ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tap-packages

Air-gapped Environments:

imgpkg copy \
-b registry.tanzu.vmware.com/tanzu-application-platform/tap-packages:$TAP_VERSION \
--to-tar tap-packages-$TAP_VERSION.tar \
--include-non-distributable-layers

# move to computer with registry access

# set the same envs from above
export INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER
export INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD
export INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY
export TAP_VERSION=VERSION-NUMBER
export INSTALL_REPO=TARGET-REPOSITORY


imgpkg copy \
--tar tap-packages-$TAP_VERSION.tar \
--to-repo $INSTALL_REGISTRY_HOSTNAME/${INSTALL_REPO}/tap-packages \
--include-non-distributable-layers \
--registry-ca-cert-path <PATH-TO-CA>

Add the Tanzu Application Platform package repository

Tanzu CLI packages are available on repositories. Adding the Tanzu Application Platform package repository makes Tanzu Build Service available for installation.

To add the Tanzu Application Platform package repository to your cluster:

Create a namespace called tap-install for deploying any component packages by running:
```
kubectl create ns tap-install
```
This namespace keeps the objects grouped together logically.

Create a registry secret by running:

tanzu secret registry add tap-registry \
  --username ${INSTALL_REGISTRY_USERNAME} \
  --password ${INSTALL_REGISTRY_PASSWORD} \
  --server ${INSTALL_REGISTRY_HOSTNAME} \
  --export-to-all-namespaces --yes --namespace tap-install

Add the Tanzu Application Platform package repository to the cluster by running:

tanzu package repository add tanzu-tap-repository \
  --url ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tap-packages:$TAP_VERSION \
  --namespace tap-install

Get the status of the Tanzu Application Platform package repository, and ensure that the status updates to Reconcile succeeded by running:

tanzu package repository get tanzu-tap-repository --namespace tap-install

For example:

$ tanzu package repository get tanzu-tap-repository --namespace tap-install
- Retrieving repository tap...
NAME:          tanzu-tap-repository
VERSION:       16253001
REPOSITORY:    tapmdc.azurecr.io/mdc/1.4.0/tap-packages
TAG:           1.5.0
STATUS:        Reconcile succeeded
REASON:

Install the `buildservice` Tanzu Application Platform Profile

The tap.tanzu.vmware.com package installs predefined sets of packages based on your profile settings. This is done by using the package manager installed by Tanzu Cluster Essentials.

This package now includes a profile that installs Tanzu Build Service as a standalone component.

About Tanzu Build Service Dependencies

Tanzu Build Service supports multiple methods of installing dependencies, for example, buildpacks, stacks, and builders. The method of dependency installation must be decided before installing Tanzu Build Service and each has a slightly different installation process. Tanzu Build Service dependencies fall into two categories, named full and lite. Deciding which one to use is the first step. For more information, see Dependencies in the Tanzu Application Platform documentation.

If installing the full dependencies, you can install the Full Deps Package repository, which is relocated to your registry and supports air-gapped environments, but needs to be upgraded with new releases of Tanzu Build Service to stay up to date. Alternatively, there is an automatic dependency updater that pulls new dependencies from VMware Tanzu Network as they are released. This can provide for a shorter time to receive updates, but requires cluster Internet access and has a longer initial install due to the relocation of dependencies that happens during installation.

If installing the lite dependencies, you can use the bundled dependencies that are in the Tanzu Build Service package or enable the automatic dependency updates.

Set Up Install Secrets

Create a secret for your kp-default-repository in the tap-install namespace:
```
tanzu secret registry add kp-default-repository \
  --username ${KP_DEFAULT_REPOSITORY_USERNAME} \
  --password ${KP_DEFAULT_REPOSITORY_PASSWORD} \
  --server ${REGISTRY_HOSTNAME} \
  --yes --namespace tap-install
```
Where:
- REGISTRY_HOSTNAME is the host name for your registry. (i.e. gcr.io)
- KP_DEFAULT_REPOSITORY_USERNAME is the registry user name. Same value as used during relocation.
- KP_DEFAULT_REPOSITORY_PASSWORD is the registry password. Same value as used during relocation.
Create a secret for VMware Tanzu Network in the tap-install namespace. This is only required if enabling automatic dependency updates.
```
tanzu secret registry add tanzunet-registry \
  --username ${TANZUNET_USERNAME} \
  --password ${TANZUNET_PASSWORD} \
  --server "registry.tanzu.vmware.com" \
  --yes --namespace tap-install
```
Where:
- TANZUNET_REGISTRY_USERNAME is used to pull dependencies from VMware Tanzu Network.
- TANZUNET_REGISTRY_PASSWORD is used to pull dependencies from VMware Tanzu Network.

Create Values File

Create a tap-values.yaml file that contains the following:

ceip_policy_disclosed: true
profile: buildservice
buildservice:
	kp_default_repository: <REPOSITORY>
	kp_default_repository_secret:
		name: kp-default-repository
		namespace: tap-install
	exclude_dependencies: <EXCLUDE_DEPENDENCIES>
	ca_cert_data: <CA_CERT_CONTENTS>
	injected_sidecar_support: <INJECTED_SIDECAR_SUPPORT>
	generate_slsa_attestation: <GENERATE_SLSA_ATTESTATION>
	kubernetes_version: <KUBERNETES_VERSION>
	kubernetes_distribution: <KUBERNETES_DISTRIBUTION>

Where:

REPOSITORY is a writable repository in your registry. Tanzu Build Service Dependencies are written to this location.
- Docker Hub has the form my-dockerhub-username/build-service or index.docker.io/my-dockerhub-username/build-service.
- gcr.io has the form gcr.io/my-project/build-service.
- Harbor has the form my-harbor.io/my-project/build-service.
EXCLUDE_DEPENDENCIES you must set this to true if you want to install Tanzu Build Service Full Dependencies package repository. This prevents Tanzu Build Service from installing the bundled lite dependencies.
CA_CERT_CONTENTS must be provided when using a registry that is signed by a Custom Cert. This is the value of the PEM-encoded CA certificate that is used during the build time. For more information about adding CA certificate to the run image, see Using custom CA certificates at run time.
(Optional) INJECTED_SIDECAR_SUPPORT use to enable support for Tanzu Service Mesh and Istio (Documentation).
(Optional) GENERATE_SLSA_ATTESTATION use to enable support for SLSA attestations.
KUBERNETES_VERSION is the major.minor version of Kubernetes, for example, 1.25 (Optional when not installing on OpenShift).
KUBERNETES_DISTRIBUTION is the Kubernetes provider that you are using. This field is required to deploy on OpenShift.

Example `tap-values.yml`

Example values for bundled lite dependency install:

ceip_policy_disclosed: true
profile: buildservice
buildservice:
  kp_default_repository: gcr.io/my-project/tbs
  kp_default_repository_secret:
	name: kp-default-repository
	namespace: tap-install

Example values for full deps package repository install:

ceip_policy_disclosed: true
profile: buildservice
buildservice:
  kp_default_repository: gcr.io/my-project/tbs
  kp_default_repository_secret:
	name: kp-default-repository
	namespace: tap-install
  exclude_dependencies: true

Example values for full deps automatic dependency updater install:

ceip_policy_disclosed: true
profile: buildservice
buildservice:
  kp_default_repository: gcr.io/my-project/tbs
  kp_default_repository_secret:
	name: kp-default-repository
	namespace: tap-install
  exclude_dependencies: true
  dependency_updates:
    allow: true
    scope: all

Example values for lite deps automatic dependency updater install:

ceip_policy_disclosed: true
profile: buildservice
buildservice:
  kp_default_repository: gcr.io/my-project/tbs
  kp_default_repository_secret:
	name: kp-default-repository
	namespace: tap-install
  dependency_updates:
    allow: true
    scope: all

Install the Tanzu Application Platform package

List version information for the package by running:

tanzu package available list tap.tanzu.vmware.com --namespace tap-install

Install the package by running:
```
tanzu package install tap -p tap.tanzu.vmware.com -v $TAP_VERSION --values-file tap-values.yaml -n tap-install
```
Where $TAP_VERSION is the Tanzu Application Platform version environment variable you defined earlier.

Verify the package install by running:

tanzu package installed get tap -n tap-install

(Optional) To install the full dependencies, see Installing Full Dependencies later in this topic.
(Optional) To configure automatic dependency updates, see Updating Dependencies.

Installing on OpenShift

Installing Tanzu Build Service on OpenShift requires some extra steps.

Follow the installation steps above, but when creating the tap-values.yml add the following under the buildservice key:
```
...
buildservice:
	kubernetes_distribution: openshift
...
```
On OpenShift v4.10 and below, you must configure any namespaces that will have Image or Build resources after installation.

To do this you must configure RBAC for the service account used for Image resources (the default service account is used by default).

Apply the following RoleBinding:
```
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tbs-restricted-with-seccomp
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:tbs:scc:restricted-with-seccomp
subjects:
- kind: ServiceAccount
  namespace: <BUILD-NAMESPACE>
  name: <BUILD-SERVICE-ACCOUNT>
```
Where:
- BUILD-NAMESPACE is the namespace where Image and Build resources are created.
- BUILD-SERVICE-ACCOUNT is the service account used for Image resources (default by default).

Install the Full Dependencies Package

Get the latest version of the Tanzu Application Platform package by running:
```
tanzu package available list tap.tanzu.vmware.com --namespace tap-install
```
If you have not done so already, you must exclude the default dependencies by adding the key-value pair exclude_dependencies: true to your tap-values.yaml file under the buildservice section. For example:
```
buildservice:
  exclude_dependencies: true
```
If you have not updated your Tanzu Application Platform package installation after adding the key-value pair exclude_dependencies: true to your values file, perform the update by running:
```
tanzu package installed update tap --namespace tap-install --values-file VALUES-FILE
```
Where VALUES-FILE is the path to the tap-values.yaml file you edited earlier.
Relocate the Tanzu Build Service full dependencies package repository by doing one of the following:
- Relocate the images directly for online installation:
```
imgpkg copy \
  -b registry.tanzu.vmware.com/tanzu-application-platform/full-deps-package-repo:VERSION \
  --to-repo ${INSTALL_REGISTRY_HOSTNAME}/full-deps-package-repo
```
  Where VERSION is the version of the Tanzu Application Platform package you retrieved earlier.
- Relocate the images to an external storage device and then to the registry in the air-gapped environment:
```
imgpkg copy \
  -b registry.tanzu.vmware.com/tanzu-application-platform/full-deps-package-repo:VERSION \
  --to-tar=full-deps-package-repo.tar

# move full-deps-package-repo.tar to environment with registry access
imgpkg copy \
  --tar full-deps-package-repo.tar \
  --to-repo=INSTALL-REGISTRY-HOSTNAME/TARGET-REPOSITORY/full-deps-package-repo
```
  Where:
  - VERSION is the version of the Tanzu Application Platform package you retrieved earlier.
  - INSTALL-REGISTRY-HOSTNAME is your container registry.
  - TARGET-REPOSITORY is your target repository.
Add the Tanzu Build Service full dependencies package repository by running:
```
tanzu package repository add full-deps-package-repo \
  --url INSTALL-REGISTRY-HOSTNAME/TARGET-REPOSITORY/full-deps-package-repo:VERSION \
  --namespace tap-install
```
Where:
- INSTALL-REGISTRY-HOSTNAME is your container registry.
- TARGET-REPOSITORY is your target repository.
- VERSION is the version of the Tanzu Application Platform package you retrieved earlier.
Create a new tbs-full-deps-values.yaml and copy the kp_default_repository key-value pair from your tap-values.yaml or tbs-values.yaml:
```
---
 kp_default_repository: "REPO-NAME"
 kp_default_repository_secret:
   name: kp-default-repository-creds
   namespace: tap-install
```
Where REPO-NAME is copied from the buildservice.kp_default_repository field in your tap-values.yaml or tbs-values.yaml.
1. (Optional) Install the UBI builder.
  
  The UBI builder uses Red Hat Universal Base Image (UBI) v8 for both build and run images. This builder only supports Java and Node.js. To install the UBI builder, add the key-value pair enable_ubi_builder: true to your tbs-full-deps-values.yaml.
```
---
enable_ubi_builder: true
```
2. (Optional) Install the Static builder.
  
  The Static builder uses Ubuntu Jammy for both build images and a minimal static run image. This builder only supports Golang. To install the Static builder, add the key-value pair enable_static_builder: true to your tbs-full-deps-values.yaml.
```
---
enable_static_builder: true
```

Install the full dependencies package by running:

tanzu package install full-deps \
  --package full-deps.buildservice.tanzu.vmware.com \
  --version "> 0.0.0" \
  --namespace tap-install \
  --values-file VALUES-FILE

Where VALUES-FILE is the path to the tbs-full-deps-values.yaml you created earlier.