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 descriptor or bundled dependencies, VMware recommends at least 1 GB of registry storage.
  • If installing using the full descriptor, which is intended for production use and 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:

  • Tanzu Build Service Dependencies
  • Buildpacks for VMware Tanzu
  • Stacks for VMware Tanzu

Install Required Software

• Follow these instructions to install the Tanzu CLI

• Follow these instructions to install Cluster Essentials

  • 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

1. Log in to your image registry by running:

   docker login MY-REGISTRY
   

   Where MY-REGISTRY is your own registry.

2. 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

1. 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.

2. 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:

1. 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.

2. 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
   

3. 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
   

4. 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

1. 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.

2. Create a secret for VMware Tanzu Network in the tap-install namespace

Important: There is a known issue with the automatic dependency updater not being created when installing TBS from Tanzu Application Profile v1.6.1 or v1.6.2. See the depedency updater hotfix for workaround.

This is only required if enabling automatic dependency updates.

```console
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
	tanzunet_secret:
		name: tanzunet-registry
		namespace: tap-install
	exclude_dependencies: <EXCLUDE_DEPENDENCIES>
	enable_automatic_dependency_updates: <ENABLE_AUTOMATIC_DEPENDENCY_UPDATES>
	ca_cert_data: <CA_CERT_CONTENTS>	
	descriptor_name: <DESCRIPTOR_NAME>
	injected_sidecar_support: <INJECTED_SIDECAR_SUPPORT>
	kubernetes_version: <KUBERNETES_VERSION>
	kubernetes_distribution: <KUBERNETES_DISTRIBUTION>

Note: There is a known issue with using tanzunet_secret on Tanzu Application Platform version v1.5.4, the workaround is to remove that block and use the tanzunet_username and tanzunet_password fields instead.

...
buildservice:
	# tanzunet_secret:
	#   name: tanzunet-registry
	#   namespace: tap-install
    tanzunet_username: <TANZUNET_REGISTRY_USERNAME>
    tanzunet_password: <TANZUNET_REGISTRY_PASSWORD>
...

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.
• ENABLE_AUTOMATIC_DEPENDENCY_UPDATES is set to true to pull dependencies directly from Tanzu Network as soon as they are released. This is not supported in air-gapped environments. If this is set to true, exclude_dependencies: true is required.
• EXCLUDE_DEPENDENCIES must be set to true if ENABLE_AUTOMATIC_DEPENDENCY_UPDATES is true or if the TBS Full Deps package repository will be installed. This prevents Tanzu Build Service from installing its bundled lite dependencies.
• DESCRIPTOR-NAME is the name of the descriptor to import automatically. For more information about which descriptor to choose for your workload and use case, see Descriptors. Available options:
  • full contains all dependencies.
  • lite smaller footprint used for speeding up installs. Requires Internet access on the cluster.
• 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.
• INJECTED_SIDECAR_SUPPORT (Optional) enable support for Tanzu Service Mesh and Istio (Documentation)
• 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
  tanzunet_secret:
    name: tanzunet-registry
    namespace: tap-install
  enable_automatic_dependency_updates: true
  descriptor_name: full

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
  exclude_dependencies: true
  tanzunet_secret:
    name: tanzunet-registry
    namespace: tap-install
  enable_automatic_dependency_updates: true
  descriptor_name: lite

Install The Package

1. List version information for the package by running:

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

2. 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.

3. Verify the package install by running:

   tanzu package installed get tap -n tap-install
   

This might take 30 minutes if automatic dependency updates are being used

Installing on OpenShift

Installing Tanzu Build Service on OpenShift requires some extra steps.

1. Follow the installation steps above, but when creating the tap-values.yml add the following under the buildservice key:

   ...
   buildservice:
   	kubernetes_distribution: openshift
   ...
   

2. 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

To install full dependencies:

1. Get the version of the Tanzu Build Service by running:

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

2. Relocate the Tanzu Build Service full dependencies package repository by running:

   For Non-Air-gapped Environments:

   imgpkg copy -b registry.tanzu.vmware.com/tanzu-application-platform/full-tbs-deps-package-repo:VERSION \
   --to-repo=INSTALL-REGISTRY-HOSTNAME/TARGET-REPOSITORY/tbs-full-deps
   

   For Air-gapped Environments:

   imgpkg copy -b registry.tanzu.vmware.com/tanzu-application-platform/full-tbs-deps-package-repo:VERSION \
     --to-tar=tbs-full-deps.tar
   # move tbs-full-deps.tar to environment with registry access
   imgpkg copy --tar tbs-full-deps.tar \
     --to-repo=INSTALL-REGISTRY-HOSTNAME/TARGET-REPOSITORY/tbs-full-deps
   

   Where:

   • VERSION is the version of the Tanzu Build Service package you retrieved earlier.
   • INSTALL-REGISTRY-HOSTNAME is your registry.
   • TARGET-REPOSITORY is your target repository.

3. Add the Tanzu Build Service full dependencies package repository by running:

   tanzu package repository add tbs-full-deps-repository \
     --url INSTALL-REGISTRY-HOSTNAME/TARGET-REPOSITORY/tbs-full-deps:VERSION \
     --namespace tap-install
   

   Where:

   • INSTALL-REGISTRY-HOSTNAME is your registry.
   • TARGET-REPOSITORY is your target repository.
   • VERSION is the version of the Tanzu Build Service package you retrieved earlier.

4. Install the full dependencies package by running:

   tanzu package install full-tbs-deps -p full-tbs-deps.tanzu.vmware.com -v VERSION -n tap-install
   

   Where VERSION is the version of the Tanzu Build Service package you retrieved earlier.

Hotfix for Automatic Dependency Updater on Tanzu Application Platform v1.6.1 and v1.6.2

A known issue in Tanzu Application Platform (TAP) is causing the automatic dependency updater to not be created in TAP v1.6.1 and v1.6.2. If you would like to enable automatic dependency updates, a hotfix for this is available and can be installed after the TBS has been installed or upgraded.

Installing the hotfix

To install Tanzu Build Service with the Dependency Updater Hotfix for Tanzu Application Platform v1.6.1 or v1.6.2:

1. Create a copy of your tap-values.yaml and call it hotfix-values.yaml. Make sure it has enable_automatic_dependency_updates: true, descriptor_name, and optionally descriptor_version set.

2. Remove the enable_automatic_dependency_updates, descriptor_name, and descriptor_version fields from your tap-values.yaml

3. Follow the instructions in the package install instructions to install TBS.

4. Add the Tanzu Build Service hotfix package repository by running:

   tanzu package repository add tbs-tap-install-hotfix \
     --url registry.tanzu.vmware.com/build-service/tap-profile-install-hotfix:tbs-1.11.10 \
     --namespace tap-install
   

5. Install the hotfix package by running:

   tanzu package install tbs-tap-install-hotfix -p tap-install.hotfix.buildservice.tanzu.vmware.com -v 1.11.10 -n tap-install --values-file hotfix-values.yaml
   

Uninstalling the hotfix

When upgrading away from Tanzu Application v1.6.1 or v1.6.2, the hotfix needs to be uninstalled from the cluster first:

1. Delete the hotfix package by running:

   tanzu package installed delete tbs-tap-install-hotfix -n tap-install
   

2. Delete the hotfix package repository by running:

   tanzu package repository delete tbs-tap-install-hotfix -n tap-install
   

3. Re-add the enable_automatic_dependency_updates, descriptor_name, and descriptor_version fields to your tap-values.yaml.

4. Upgrade Tanzu Application Platform.