Install Tanzu Build Service without kapp controller

This topic tells you how to install Tanzu Build Service (commonly known as TBS) without kapp controller.

Important

This method of installation is now deprecated in favor of Installing using a profile.

Reasons to use the previous installation method include:

• You do not want to install kapp controller on your cluster
• You want to make custom changes to the Tanzu Build Service installation via ytt templating or overlays

Prerequisites

Before you install Build Service, you must:

• Be on Kubernetes cluster v1.23 or later

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

• Ensure that all worker nodes have at least 50 GB of ephemeral storage allocated to them.

  • To do this on TKGs, mount a 50GB volume at /var/lib/containerd to the worker nodes in the TanzuKubernetesCluster resource that corresponds to your TKGs cluster. These instructions show how to configure storage on worker nodes.

• Have access to a container registry to install Tanzu Build Service and store the application images created.

  • 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, VMware recommends 1 GB of registry storage.
  • If installing using the full descriptor, which is intended for production use and offline environments, VMware recommends 10 GB of available storage.
  • This registry space suggestion does not include the space used for application images Tanzu Build Service builds.

• 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
  • For users on EKS running Kubernetes 1.23, the Amazon EBS CSI Driver is required due to the CSIMigrationAWS in this K8s version version on EKS

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

• Navigate to the following pages in Tanzu Network and accept all EULAs highlighted in yellow.

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

• 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.10.x with Tanzu Build Service v1.10.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.

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

Note: Clusters running with Containerd 1.4.1, 1.5.6, and 1.5.7 are not compatible with Tanzu Build Service. Notably, TKG 1.2.1 and TKGi 1.13.0 & 1.13.1 use these versions of Containerd, a different version must be used.

Note: TKGs clusters running Kubernetes 1.20.0-1.20.6 are not compatible with Tanzu Build Service.

Deprecated Features

The legacy Cloud Native Buildpack Bill of Materials (CNB BOM) format is deprecated and is now deactivated by default in Tanzu Build Service. If required, you can activate it manually by passing --data-value-yaml include_legacy_bom=true to ytt when processing the Tanzu Build Service bundle or by adding include_legacy_bom=true to your tbs-values.yml file. The feature will be removed in Tanzu Build Service v1.13.

Installing

Create a kubernetes cluster where you would like to install build service and target the cluster as follows:

kubectl config use-context <CONTEXT-NAME>

Relocate images to a registry

This procedure relocates images from the Tanzu Network registry to an internal image registry.

1. Log in to the image registry where you want to store the images by running:

   • If using the docker CLI, run:

     docker login <IMAGE-REGISTRY>
     

     Where IMAGE-REGISTRY is the name of the image registry where you want to store the images.

   • If using the crane CLI, run:

     crane auth login <IMAGE-REGISTRY>
     

     Where IMAGE-REGISTRY is the name of the image registry where you want to store the images.

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

3. Relocate the images with the Carvel tool imgpkg by running:

   imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION>" --to-repo <IMAGE-REPOSITORY>
   

   Where:

   • TBS-VERSION is the version full version (1.10.x) of Tanzu Build Service that you want to install.
   • IMAGE-REPOSITORY is the repository in your registry that you want to relocate images to.

   Note: When relocating, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, IMAGE-REGISTRY/some-repo/build-service.
   
   Exception: When relocating to Dockerhub, you must provide the Dockerhub username and a repository name that imgpkg uses for relocation. For example, my-dockerhub-account/build-service.

   For example:

   • Dockerhub imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION>" --to-repo my-dockerhub-account/build-service
   • GCR imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION>" --to-repo gcr.io/my-project/build-service
   • Artifactory imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION>" --to-repo artifactory.com/my-project/build-service
   • Harbor imgpkg copy -b "registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION>" --to-repo harbor.io/my-project/build-service

   Note: During relocation, imgpkg reports the following:
   Skipped layer due to it being non-distributable. If you would like to include non-distributable layers, use the –include-non-distributable flag.
   This is due to windows-based images shipped with Tanzu Build Service and can be ignored. For more details see the FAQ.

Install Tanzu Build Service

There are two ways to install Tanzu Build Service:

1. Using a public registry (eg. GCR, Dockerhub) or an internal registry that uses a trusted certificate (eg. Lets Encrypt)
2. Using an internal registry that uses a self-signed CA certificate (eg. Harbor, Artifactory)

Install Tanzu Build Service Public Registry

1. Pull the Tanzu Build Service bundle image locally using imgpkg:

   imgpkg pull -b "<IMAGE-REPOSITORY>:<TBS-VERSION>" -o /tmp/bundle
   

   Where TBS-VERSION and IMAGE-REPOSITORY are the same values used during relocation.

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

   Tanzu Build Service ships with a dependency updater that can update ClusterStacks, ClusterStores, ClusterBuilders, and the CNB Lifecycle from TanzuNet automatically. Enabling this feature keeps Images up to date with the latest security patches and fixes, and is highly recommended. To enable this feature, include your TanzuNet credentials, descriptor_name, and enable_automatic_dependency_updates when running the install command below:

   ytt -f /tmp/bundle/config/ \
     -v kp_default_repository='<IMAGE-REPOSITORY>' \
     -v kp_default_repository_username='<REGISTRY-USERNAME>' \
     -v kp_default_repository_password='<REGISTRY-PASSWORD>' \
     --data-value-yaml pull_from_kp_default_repo=true \
     -v tanzunet_username='<TANZUNET-USERNAME>' \
     -v tanzunet_password='<TANZUNET-PASSWORD>' \
     -v descriptor_name='<DESCRIPTOR-NAME>' \
     --data-value-yaml enable_automatic_dependency_updates=true \
     | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
     | kapp deploy -a tanzu-build-service -f- -y
   

   You can check the status of the DependencyUpdater by running:

   kubectl -n build-service get TanzuNetDependencyUpdater dependency-updater -o yaml
   

   Alternatively, if you prefer to manage dependencies manually, leave the TanzuNet credentials, descriptor_name, and enable_automatic_dependency_updates out of the install.

   ytt -f /tmp/bundle/config/ \
     -v kp_default_repository='<IMAGE-REPOSITORY>' \
     -v kp_default_repository_username='<REGISTRY-USERNAME>' \
     -v kp_default_repository_password='<REGISTRY-PASSWORD>' \
     --data-value-yaml pull_from_kp_default_repo=true \
     | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
     | kapp deploy -a tanzu-build-service -f- -y
   

   Where:

   • IMAGE-REPOSITORY is the image repository where Tanzu Build Service images exist.

     Note: This is identical to the IMAGE-REPOSITORY argument provided during imgpkg relocation command.

   • REGISTRY-USERNAME is the username you use to access the registry. gcr.io expects _json_key as the username when using JSON key file authentication.
   • REGISTRY-PASSWORD is the password you use to access the registry.

     Note: Managing Secrets for more information about how the registry username and password are used in Tanzu Build Service.

   • TANZUNET-USERNAME is the username you use to access TanzuNet
   • TANZUNET-PASSWORD is the password you use to access TanzuNet
   • 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.

   Note: You may want to pin your Tanzu Build Service to a specific descriptor version and temporarily pause the automatic update of dependencies. For details, see the FAQ section “Pinning the Tanzu Net Updater”

Installing with a CA certificate for internal registry

To install Tanzu Build Service with an internal registry that requires providing a CA certificate such as Harbor, use the normal installation command with the CA certificate file passed in with a -f flag:

ytt -f /tmp/bundle/config/ \
  -f <PATH-TO-CA> \
  -v kp_default_repository='<IMAGE-REPOSITORY>' \
  -v kp_default_repository_username='<REGISTRY-USERNAME>' \
  -v kp_default_repository_password='<REGISTRY-PASSWORD>' \
  --data-value-yaml pull_from_kp_default_repo=true \
  -v tanzunet_username='<TANZUNET-USERNAME>' \
  -v tanzunet_password='<TANZUNET-PASSWORD>' \
  -v descriptor_name='<DESCRIPTOR-NAME>' \
  --data-value-yaml enable_automatic_dependency_updates=true \
  | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
  | kapp deploy -a tanzu-build-service -f- -y

Where:

• PATH-TO-CA is the path to the registry root CA. This CA is required to enable Build Service to interact with internally deployed registries. This is the CA that was used while deploying the registry.
• IMAGE-REPOSITORY is the image repository where Tanzu Build Service images exist.

  Note: This is identical to the IMAGE-REPOSITORY argument provided during imgpkg relocation command.
  
  Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you encounter an error similar to: Error: invalid credentials, ensure registry credentials for ‘index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go’ are available locally

• REGISTRY-USERNAME is the username you use to access the registry. gcr.io expects _json_key as the username when using JSON key file authentication.
• REGISTRY-PASSWORD is the password you use to access the registry.

  Note: Managing Secrets for more information about how the registry username and password are used in Tanzu Build Service.

• TANZUNET-USERNAME is the username you use to access TanzuNet
• TANZUNET-PASSWORD is the password you use to access TanzuNet

Additional Configuration

You can add other optional parameters using the -v flag:

• admin_users: A comma-separated list of users who are granted admin privileges on Build Service.
• admin_groups: A comma-separated list of groups that are granted admin privileges on Build Service.
• http_proxy: The HTTP proxy to use for network traffic.
• https_proxy: The HTTPS proxy to use for network traffic.
• no_proxy: A comma-separated list of host names, IP addresses, or IP address ranges in CIDR format. These must not use a proxy.

Note: When proxy server is enabled using http_proxy or https_proxy, traffic to the Kubernetes API server also flows through the proxy server. You can circumvent this known limitation by using no_proxy to specify the Kubernetes API server.

Use AWS IAM for Authentication with ECR

You can install Tanzu Build Service using AWS IAM roles for authentication with Amazon Elastic Container Registry (ECR) on Amazon Elastic Kubernetes Service (EKS) clusters.

There are two additional steps required:

1. Install Tanzu Build Service with AWS IAM for Authentication with ECR
2. Configure the build namespace for IAM Auth with ECR

Install Tanzu Build Service with AWS IAM for Authentication with ECR

To install with AWS IAM for Authentication with ECR:

1. Before installing Tanzu Build Service, create a repository in ECR to use for the kp_default_repository.

2. Configure an AWS IAM role that has read and write access to the kp_default_repository and a trust policy for the EKS cluster. The minimum required permissions can be found here.

3. Follow the Tanzu Build Service installation steps until the ytt command.

4. Install Tanzu Build Service the following ytt command, which replaces kp_default_repository_username/password with kp_default_repository_aws_iam_role_arn:

   ytt -f /tmp/bundle/config/ \
     -v kp_default_repository='IMAGE-REPOSITORY' \
     -v kp_default_repository_aws_iam_role_arn='INSTALL-IAM-ROLE-ARN'
     -v tanzunet_username='TANZUNET-USERNAME' \
     -v tanzunet_password='TANZUNET-PASSWORD' \
     -v descriptor_name='DESCRIPTOR-NAME' \
     --data-value-yaml enable_automatic_dependency_updates=true \
     | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
     | kapp deploy -a tanzu-build-service -f- -y
   

   Where:

   • IMAGE-REPOSITORY is the image repository where Tanzu Build Service images are located.
   • INSTALL-IAM-ROLE-ARN is the AWS IAM role Amazon Resource Name (ARN) for the role configured earlier. For example, arn:aws:iam::xyz:role/my-install-role.
   • TANZUNET-USERNAME is the username you use to access VMware Tanzu Network.
   • TANZUNET-PASSWORD is the password you use to access VMware Tanzu Network.
   • 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.

Configure the build namespace for IAM Auth with ECR

Similar to configuring a secret in the build namespace for registry authentication, the build namespace requires configuration for Tanzu Build Service to use AWS IAM authentication for ECR in builds.

To configure the build namespace for IAM Auth with ECR:

1. Configure an AWS IAM role that has read and write access to the ECR registry location to store build images. This can be the same repository used during installation, in which case, you can use the same AWS ARN.

2. For the service account used for Image resources, add an annotation including the role ARN configured earlier.

   kubectl annotate serviceaccount -n BUILD-NAMESPACE SERVICE-ACCOUNT-NAME \
     eks.amazonaws.com/role-arn=${BUILD-IAM-ROLE-ARN}
   

   Where:

   • BUILD-NAMESPACE is the name of your build namespace.
   • SERVICE-ACCOUNT-NAME is the service account used for Image resources. This is default if unset.
   • BUILD-IAM-ROLE-ARN is the AWS IAM role ARN for the role configured earlier. For example, arn:aws:iam::xyz:role/my-build-role.

3. To create an Image resource with this service account, run:

   kp image save my-ecr-image --tag 12345.ecr.com/my-repo --service-acount=SERVICE-ACCOUNT-NAME -n BUILD-NAMESPACE
   

Configuring TKGI as an OIDC Provider

The authentication and authorization processes for Build Service use a combination of RBAC rules and third-party authentication, including OpenID Connect (OIDC). You may configure UAA as an OIDC provider for your TKGI deployment to provide authentication for Build Service.

To configure UAA as an OIDC provider for your TKGI deployment:

1. Navigate to the OpsManager Installation Dashboard.

2. Click the TKGI tile.

3. Select UAA.

4. Under Configure created clusters to use UAA as the OIDC provider, select Enable.

5. Ensure the values in the UAA OIDC Groups Prefix and UAA OIDC Username Prefix fields are the same and record them. For example, "oidc:". You need these values during the installation of Build Service.

   Note: Ensure you add a : at the end of the desired prefix.

6. Click Save.

7. In the OpsManager Installation Dashboard, click Review Pending Changes, then Apply Changes.

Installation to Air-Gapped Environment

Note: The TanzuNetDependencyUpdater cannot be used in air-gapped environments. Do not include Tanzu Net credentials for air-gapped installations.

Tanzu Build Service can be installed to a Kubernetes Cluster and registry that are air-gapped from external traffic.

An air-gapped environment often uses an internal registry with a self-signed CA certificate and you need access to this CA certificate file to install Tanzu Build Service.

Note: If you are using a CA certificate that is trusted (eg. Lets Encrypt) you do not need the CA certificate file.

Relocate Images to a Registry (Air-Gapped)

This procedure relocates images from the Tanzu Network registry to an internal image registry via a local machine.

The local machine must have write access to the internal registry.

1. Log in to the image registry where you want to store the images by running:

   • If using the docker CLI, run:

     docker login <IMAGE-REGISTRY>
     

     Where IMAGE-REGISTRY is the name of the image registry where you want to store the images.

   • If using the crane CLI, run:

     crane auth login <IMAGE-REGISTRY>
     

     Where IMAGE-REGISTRY is the name of the image registry where you want to store the images.

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

3. Copy the Tanzu Build Service bundle to your local machine as a tar with the Carvel tool imgpkg by running:

   imgpkg copy -b registry.tanzu.vmware.com/build-service/bundle:<TBS-VERSION> --to-tar=/tmp/tanzu-build-service.tar
   

   Where TBS-VERSION is the version of Tanzu Build Service you want to install.

4. Move the output file tanzu-build-service.tar to a machine that has access to the air-gapped environment.

5. Unpackage the images from your local machine to the internal registry:

   imgpkg copy --tar /tmp/tanzu-build-service.tar \
     --to-repo=<IMAGE-REPOSITORY> \
     --registry-ca-cert-path <PATH-TO-CA>
   

   Where:

   • IMAGE-REPOSITORY is the repository in your registry that you want to relocate images to.
   • PATH-TO-CA is the path to the registry CA certificate file.

   Note:The IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, IMAGE-REGISTRY/some-repo/build-service.
   
   Exception: When relocating to Dockerhub, you must provide the Dockerhub username and an image name that imgpkg uses for relocation. For example, my-dockerhub-account/build-service.

   For example:

   • Dockerhub imgpkg copy --tar /tmp/tanzu-build-service.tar --to-repo=my-dockerhub-account/build-service --registry-ca-cert-path ca.crt
   • GCR imgpkg copy --tar /tmp/tanzu-build-service.tar --to-repo=gcr.io/my-project/build-service --registry-ca-cert-path ca.crt
   • Artifactory imgpkg copy --tar /tmp/tanzu-build-service.tar --to-repo=artifactory.com/my-project/build-service --registry-ca-cert-path ca.crt
   • Harbor imgpkg copy --tar /tmp/tanzu-build-service.tar --to-repo=harbor.io/my-project/build-service --registry-ca-cert-path ca.crt

Installing (Air-Gapped)

Note: The TanzuNetDependencyUpdater cannot be used in air-gapped environments. Do not include Tanzu Net credentials for air-gapped installations.

Once the images have been relocated, installation is the same as a regular install.

1. Pull the Tanzu Build Service bundle image locally using imgpkg:

   imgpkg pull -b "<IMAGE-REPOSITORY>:<TBS-VERSION>" -o /tmp/bundle
   

   Where TBS-VERSION and IMAGE-REPOSITORY are the same values used during relocation.

2. 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 <PATH-TO-CA> \
     -v kp_default_repository='<IMAGE-REPOSITORY>' \
     -v kp_default_repository_username='<REGISTRY-USERNAME>' \
     -v kp_default_repository_password='<REGISTRY-PASSWORD>' \
     --data-value-yaml pull_from_kp_default_repo=true \
     --data-value-yaml exclude_dependencies=true \
     | kbld -f /tmp/bundle/.imgpkg/images.yml -f- \
     | kapp deploy -a tanzu-build-service -f- -y
   

   Where:

   • PATH-TO-CA is the path to the registry root CA. This CA is required to enable Build Service to interact with internally deployed registries. This is the CA that was used while deploying the registry.
   • IMAGE-REPOSITORY is the image repository where Tanzu Build Service images exist.

     Note: This is identical to the IMAGE-REPOSITORY argument provided during imgpkg relocation command.

   • REGISTRY-USERNAME is the username you use to access the registry. gcr.io expects _json_key as the username when using JSON key file authentication.
   • REGISTRY-PASSWORD is the password you use to access the registry.

     Note: Managing Secrets for more information about how the registry username and password are used in Tanzu Build Service.

Additional Configuration

You can add other optional parameters using the -v flag:

• admin_users: A comma-separated list of users who are granted admin privileges on Build Service.
• admin_groups: A comma separated list of groups that are granted admin privileges on Build Service.

Import Tanzu Build Service Dependencies (Air-Gapped)

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

For air-gapped environments, dependencies must be imported with the kp cli and the Dependency Descriptor bundle image (registry.tanzu.vmware.com/tbs-dependencies/full) from the Tanzu Build Service Dependencies page.

Relocate Tanzu Build Service Dependency Images (Air-Gapped)

1. First, find the latest version of the descriptor from the Tanzu Build Service Dependencies page.

2. To import these dependencies into an air-gapped environment, they must first be pulled locally. Use imgpkg and the <VERSION> from the previous step:

   imgpkg copy -b registry.tanzu.vmware.com/tbs-dependencies/full:<VERSION> \
     --to-tar=tbs-dependencies.tar
   

   Note: You must be logged in locally to the Tanzu Network registry.

3. Move the output file tbs-dependencies.tar to a machine that has access to the air-gapped environment.

4. Upload the dependencies to the Tanzu Build Service registry by running:

   imgpkg copy --tar=tbs-dependencies.tar \
     --to-repo <IMAGE-REPOSITORY> \
     --registry-ca-cert-path <PATH-TO-CA>
   

   Where:

   • IMAGE-REPOSITORY is the internal image repository where dependency images are relocated. This should be the same as kp_default_repository from installation.
   • PATH-TO-CA is the path to the registry CA certificate file.

   Note: You must be logged in locally to the registry used for IMAGE-REPOSITORY.

Import Tanzu Build Service Dependency Resources (Air-Gapped)

After the dependency images are uploaded to the internal registry, you can successfully import these images and create the corresponding Tanzu Build Service resources.

Run the following commands with imgpkg, kbld, and the kp CLI:

imgpkg pull -b <IMAGE-REPOSITORY>:<VERSION> \
  -o /tmp/descriptor-bundle \
  --registry-ca-cert-path <PATH-TO-CA>

kbld -f /tmp/descriptor-bundle/.imgpkg/images.yml \
  -f /tmp/descriptor-bundle/tanzu.descriptor.v1alpha3/descriptor-<VERSION>.yaml \
  | kp import -f - --registry-ca-cert-path <PATH-TO-CA>

Verify Installation

Verify your Build Service installation by first targeting the cluster Build Service has been installed on.

To verify your Build Service installation:

1. Download the kp binary from the Tanzu Build Service page on Tanzu Network.

2. 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>
   base-jammy    true     io.buildpacks.stacks.jammy         <image@sha256:digest>
   default       true     io.buildpacks.stacks.jammy         <image@sha256:digest>
   full          true     io.buildpacks.stacks.bionic        <image@sha256:digest>
   full-jammy    true     io.buildpacks.stacks.jammy         <image@sha256:digest>
   tiny          true     io.paketo.stacks.tiny              <image@sha256:digest>
   tiny-jammy    true     io.buildpacks.stacks.jammy.tiny    <image@sha256:digest>
   

Upgrading Tanzu Build Service

To upgrade Tanzu Build Service to a newer version, run the same commands as installation, kapp updates resources if they already exist. Re-importing dependencies is not required for upgrading Tanzu Build Service.

Uninstalling Tanzu Build Service

To uninstall Tanzu Build Service simply run the following kapp command:

kapp delete -a tanzu-build-service

Note: All Tanzu Build Service resources are deleted. Registry images created by Tanzu Build Service is not be deleted.

Updating Build Service Dependencies

Note: If you enabled the TanzuNetDependencyUpdater during install (This can be verified by running kubectl get TanzuNetDependencyUpdater -A you do not need to do anything to manage your Tanzu Build Service dependencies

Use the following documentation to keep applications patched and up-to-date with Tanzu Build Service:

To keep dependencies up-to-date, see Updating Build Service Dependencies

To manage Stacks, see Managing Stacks

To manage Buildpack Stores, see Managing Stores

Ensuring Access to Cluster Builders

In order to use Cluster Builders, such as the ones installed with Tanzu Build Service, we suggest to install Tanzu Build Service to a repository that is accessible by the nodes in the kubernetes cluster without credentials.

If this is not desired, see When to use Synchronized Secrets.

Ensuring the Run Image is Readable

Build Service relies on the run-image being publicly readable or readable with the registry credentials configured in a project/namespace for the builds to be executed successfully.

The location of the run image can be identified by running the following command:

kp clusterstack status <stack-name>

If the cluster stack run image is not public, you may need to create a registry secret in any namespace where Images or Builds are used. For more details on secrets in Tanzu Build Service, see Managing Secrets

This can be done with the kp CLI:

kp secret create my-registry-creds --registry example-registry.io --registry-user my-registry-user --namespace build-namespace

Next Steps

Visit the Managing Images and Builds page to learn how to create and manage a new image.

Kubernetes Permissions for Installation

The minimum Kubernetes RBAC permissions required to install Tanzu Build Service are as follows. This includes the namespaces required for the Kubernetes Roles:

---
apiVersion: v1
kind: Namespace
metadata:
  name: build-service
---
apiVersion: v1
kind: Namespace
metadata:
  name: kpack
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: build-service-install-cluster-role
rules:
  - apiGroups:
      - "admissionregistration.k8s.io"
    resources:
      - mutatingwebhookconfigurations
      - validatingwebhookconfigurations
    verbs:
      - '*'
  - apiGroups:
      - "rbac.authorization.k8s.io"
    resources:
      - clusterroles
      - clusterrolebindings
    verbs:
      - '*'
  - apiGroups:
      - "apiextensions.k8s.io"
    resources:
      - customresourcedefinitions
    verbs:
      - '*'
  - apiGroups:
      - "storage.k8s.io"
    resources:
      - storageclasses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - kpack.io
    resources:
      - builds
      - builds/status
      - builds/finalizers
      - images
      - images/status
      - images/finalizers
      - builders
      - builders/status
      - clusterbuilders
      - clusterbuilders/status
      - clusterstores
      - clusterstores/status
      - clusterstacks
      - clusterstacks/status
      - sourceresolvers
      - sourceresolvers/status
    verbs:
      - '*'
  - apiGroups:
      - "projects.vmware.com"
    resources:
      - projects
    verbs:
      - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: build-service-install-role
  namespace: build-service
rules:
  - apiGroups:
      - ""
    resources:
      - configmaps
      - secrets
      - serviceaccounts
      - services
      - namespaces
    verbs:
      - '*'
  - apiGroups:
      - "rbac.authorization.k8s.io"
    resources:
      - roles
      - rolebindings
    verbs:
      - '*'
  - apiGroups:
      - apps
    resources:
      - deployments
      - daemonsets
    verbs:
      - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kpack-install-role
  namespace: kpack
rules:
  - apiGroups:
      - ""
    resources:
      - services
      - serviceaccounts
      - namespaces
      - secrets
      - configmaps
    verbs:
      - '*'
  - apiGroups:
      - "rbac.authorization.k8s.io"
    resources:
      - roles
      - rolebindings
    verbs:
      - '*'
  - apiGroups:
      - apps
    resources:
      - deployments
      - daemonsets
    verbs:
      - '*'

The kapp command used to install Tanzu Build Service requires access to ConfigMaps in the namespace used to run kapp:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kapp-role
  namespace: <my-kapp-namespace>
rules:
  - apiGroups:
      - ""
    resources:
      - configmaps
    verbs:
      - '*'

Where the namespace <my-kapp-namespace> must be the namespace of the Kubernetes context that kapp is run in.

Minimum AWS IAM permissions for ECR IAM auth

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ecr:PutImageTagMutability",
                "ecr:StartImageScan",
                "ecr:DescribeImageReplicationStatus",
                "ecr:ListTagsForResource",
                "ecr:UploadLayerPart",
                "ecr:BatchDeleteImage",
                "ecr:ListImages",
                "ecr:BatchGetRepositoryScanningConfiguration",
                "ecr:DeleteRepository",
                "ecr:CompleteLayerUpload",
                "ecr:TagResource",
                "ecr:DescribeRepositories",
                "ecr:BatchCheckLayerAvailability",
                "ecr:ReplicateImage",
                "ecr:GetLifecyclePolicy",
                "ecr:PutLifecyclePolicy",
                "ecr:DescribeImageScanFindings",
                "ecr:GetLifecyclePolicyPreview",
                "ecr:PutImageScanningConfiguration",
                "ecr:GetDownloadUrlForLayer",
                "ecr:DeleteLifecyclePolicy",
                "ecr:PutImage",
                "ecr:UntagResource",
                "ecr:BatchGetImage",
                "ecr:DescribeImages",
                "ecr:StartLifecyclePolicyPreview",
                "ecr:InitiateLayerUpload",
                "ecr:GetRepositoryPolicy"
            ],
            "Resource": "<your repository>"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "ecr:GetRegistryPolicy",
                "ecr:BatchImportUpstreamImage",
                "ecr:CreateRepository",
                "ecr:DescribeRegistry",
                "ecr:DescribePullThroughCacheRules",
                "ecr:GetAuthorizationToken",
                "ecr:PutRegistryScanningConfiguration",
                "ecr:CreatePullThroughCacheRule",
                "ecr:DeletePullThroughCacheRule",
                "ecr:GetRegistryScanningConfiguration",
                "ecr:PutReplicationConfiguration"
            ],
            "Resource": "<your repository>"
        }
    ]
}