Installing Tanzu Build Service

Page last updated:

This topic describes how to install and configure Tanzu Build Service.

Overview

Build Service can be installed on any Kubernetes cluster (v1.16 or later) including TKGI (formerly PKS), GKE and AKS clusters. The installation instructions are divided between the TKGI installation, which uses OpenID Connect (OIDC) for authentication, and the install on other hosted Kubernetes clusters.

Upgrade path

Follow below install instructions using the latest binaries available on TanzuNet.

Prerequisites

Before you install Build Service, you must:

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

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

    • TBS uses ~5GB of registry space for installation, this does not include the space that will be used for application images.

  • 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 tool that builds, pushes, and relocates container images.

  • Download the Build Service Bundle from the Tanzu Build Service page on Tanzu Network.

    • Unarchive the Build Service Bundle file:
    tar xvf build-service-<version>.tar -C /tmp

  • 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 version 0.1.3 from TBS release 1.0.3. 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.

Installing on TKG/GKE/AKS

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:
docker login <IMAGE-REGISTRY>

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

  1. Log in to the Tanzu Network registry with your Tanzu Network credentials:
docker login registry.pivotal.io
  1. Relocate the images with the Carvel tool kbld by running:
kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository <IMAGE-REPOSITORY>

Where IMAGE-REPOSITORY is the repository in your registry that you want to relocate images to.

Note: The flag argument --lock-output /tmp/images-relocated.lock creates a file that will be used for installation.

Note: When relocating, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, IMAGE-REGISTRY/build-service.

Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, my-dockerhub-account/build-service.

For example:

  • Dockerhub kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service
  • GCR kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service
  • Artifactory kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service
  • Harbor kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service

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. Let’s Encrypt)
  2. Using an internal registry that uses a self-signed CA certificate (eg. Harbor, Artifactory)

Install Tanzu Build Service Public Registry

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

ytt -f /tmp/values.yaml \
    -f /tmp/manifests/ \
    -v docker_repository="<IMAGE-REPOSITORY>" \
    -v docker_username="<REGISTRY-USERNAME>" \
    -v docker_password="<REGISTRY-PASSWORD>" \
    | kbld -f /tmp/images-relocated.lock -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 kbld 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 will 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.

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/values.yaml \
    -f /tmp/manifests/ \
    -f <PATH-TO-CA> \
    -v docker_repository="<IMAGE-REPOSITORY>" \
    -v docker_username="<REGISTRY-USERNAME>" \
    -v docker_password="<REGISTRY-PASSWORD>" \
    | kbld -f /tmp/images-relocated.lock -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 kbld 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 will 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.

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

When importing to a registry that uses a self-signed CA certificate:

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

Using the --show-changes flag will give a summary of the resource changes for the import. You will also be asked to confirm the import. Confirmation can be skipped with --force.

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.

Note: You must be logged in locally to the registry used for `IMAGE-REGISTRY` during relocation and the Tanzu Network registry `registry.pivotal.io`.

Additional Configuration

Other optional parameters can be added using the -v flag:

  • admin_users is a comma separated list of users who will be granted admin privileges on Build Service.
  • admin_groups: a comma separated list of groups that will be 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 hostnames, IP addresses, or IP ranges in CIDR format that should not use a proxy.

Note: When proxy server is enabled using http_proxy and/or https_proxy, traffic to the kubernetes API server will also flow through the proxy server. This is a known limitation and can be circumvented by using no_proxy to specify the kubernetes API server.

Installing on TKGI (formerly PKS)

  • Install TKGI v1.7 or later. For more information, see Installing Tanzu Kubernetes Grid Integrated Edition in the TKGI documentation.

  • To install Build Service, you must configure a User Account and Authentication (UAA) client credentials.

  • Optional: configure your TKGI tile with oidc as described here.

Retrieve TKGI Cluster Credentials

This procedure retrieves the credentials that authenticate communication between kubectl and the TKGI cluster where Build Service runs.

To retrieve the TKGI cluster credentials:

  1. Log in to TKGI and get the latest kubeconfig by running:
tkgi get-kubeconfig CLUSTER-NAME -a API-URI -u USERNAME -p PASSWORD --ca-cert PATH-TO-CERTIFICATE

Where:

  • API-URI is the TKGI API server URI.
  • USERNAME is name of your cluster admin.
  • PASSWORD is the cluster admin password.
  • PATH-TO-CERTIFICATE is the path to your root CA certificate.
  • CLUSTER-NAME is the name of the TKGI cluster where Build Service runs.

This command sets the context to the CLUSTER-NAME provided.

For example:

tkgi get-kubeconfig build-cluster -a api.tkgi.example.com -u alana -p P4ssW0rd --ca-cert /var/tempest/workspaces/default/root_ca_certificate

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:
docker login <IMAGE-REGISTRY>

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

  1. Log in to the Tanzu Network registry with your Tanzu Network credentials:
docker login registry.pivotal.io
  1. Relocate the images with the Carvel tool kbld by running:
kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository <IMAGE-REPOSITORY>

Where IMAGE-REPOSITORY is the repository in your registry that you want to relocate images to.

Note: The flag argument --lock-output /tmp/images-relocated.lock creates a file that will be used for installation.

Note: When relocating, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, IMAGE-REGISTRY/build-service.

Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, my-dockerhub-account/build-service.

For example:

  • Dockerhub kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service
  • GCR kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service
  • Artifactory kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service
  • Harbor kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service

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. Let’s Encrypt)
  2. Using an internal registry that uses a self-signed CA certificate (eg. Harbor, Artifactory)

Install Tanzu Build Service Public Registry

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

ytt -f /tmp/values.yaml \
    -f /tmp/manifests/ \
    -v docker_repository="<IMAGE-REPOSITORY>" \
    -v docker_username="<REGISTRY-USERNAME>" \
    -v docker_password="<REGISTRY-PASSWORD>" \
    | kbld -f /tmp/images-relocated.lock -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 kbld 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 will 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.

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/values.yaml \
    -f /tmp/manifests/ \
    -f <PATH-TO-CA> \
    -v docker_repository="<IMAGE-REPOSITORY>" \
    -v docker_username="<REGISTRY-USERNAME>" \
    -v docker_password="<REGISTRY-PASSWORD>" \
    | kbld -f /tmp/images-relocated.lock -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 kbld 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 will 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.

Additional Configuration

Other optional parameters can be added using the -v flag:

  • admin_users is a comma separated list of users who will be granted admin privileges on Build Service.
  • admin_groups: a comma separated list of groups that will be 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 hostnames, IP addresses, or IP ranges in CIDR format that should not use a proxy.

Note: When proxy server is enabled using http_proxy and/or https_proxy, traffic to the kubernetes API server will also flow through the proxy server. This is a known limitation and can be circumvented by using no_proxy to specify the kubernetes API server.

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

When importing to a registry that uses a self-signed CA certificate:

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

Using the --show-changes flag will give a summary of the resource changes for the import. You will also be asked to confirm the import. Confirmation can be skipped with --force.

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.

Note: You must be logged in locally to the registry used for `IMAGE-REGISTRY` during relocation and the Tanzu Network registry `registry.pivotal.io`.

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 will 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

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

An air-gapped environment will often use an internal registry with a self-signed CA certificate and you will need access to this CA certificate file to install TBS.

Note: If you are using a CA certificate that is trusted (eg. Let’s Encrypt) you will 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:
docker login <IMAGE-REGISTRY>

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

  1. Log in to the Tanzu Network registry with your Tanzu Network credentials:
docker login registry.pivotal.io
  1. Package the images in a file on your local machine with the Carvel tool kbld by running:
kbld package -f /tmp/images.lock --output /tmp/packaged-images.tar

  1. Move the output file packaged-images.tar to a machine that has access to the air-gapped environment.

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

kbld unpackage -f /tmp/images.lock \
  --input /tmp/packaged-images.tar \
  --repository <IMAGE-REPOSITORY> \
  --lock-output /tmp/images-relocated.lock \
  --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 flag argument `–lock-output /tmp/images-relocated.lock` creates a file that will be used for installation.

Note: When relocating to a registry that is not Dockerhub, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, IMAGE-REGISTRY/build-service.

Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, my-dockerhub-account/build-service.

For example:

  • Dockerhub kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service --registry-ca-cert-path ca.crt
  • GCR kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service --registry-ca-cert-path ca.crt
  • Artifactory kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service --registry-ca-cert-path ca.crt
  • Harbor kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service --registry-ca-cert-path ca.crt

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.

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

Relocate Tanzu Build Service Dependency Images (Air-Gapped)

To import these dependencies into an air-gapped environment, they must first be relocated to the internal registry. Use kbld to perform this relocation similarly to installation:

  1. Download the dependency images locally:
kbld package -f descriptor-<version>.yaml \
  --output /tmp/packaged-dependencies.tar

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

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

  2. Upload the dependency images to the Tanzu Build Service registry:

kbld unpackage -f descriptor-<version>.yaml \
  --input /tmp/packaged-dependencies.tar \
  --repository <IMAGE-REPOSITORY> \
  --lock-output /tmp/dependencies-relocated.lock \
  --registry-ca-cert-path <PATH-TO-CA>

Where:

  • IMAGE-REPOSITORY is the internal image repository where dependency images will be relocated.
  • 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-REGISTRY`.

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.

Use the following command with kbld and the kp CLI:

kbld -f descriptor-<version>.yaml -f /tmp/dependencies-relocated.lock | kp import -f - --registry-ca-cert-path <path-to-ca-cert>

Installing (Air-Gapped)

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

ytt -f /tmp/values.yaml \
    -f /tmp/manifests/ \
    -f <PATH-TO-CA> \
    -v docker_repository="<IMAGE-REPOSITORY>" \
    -v docker_username="<REGISTRY-USERNAME>" \
    -v docker_password="<REGISTRY-PASSWORD>" \
    | kbld -f /tmp/images-relocated.lock -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 kbld 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 will 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.

Additional Configuration

Other optional parameters can be added using the -v flag:

  • admin_users is a comma separated list of users who will be granted admin privileges on Build Service.
  • admin_groups: a comma separated list of groups that will be granted admin privileges on Build Service.

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

Updating 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 will be 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 that will be 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 will be run in.