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.14 or later) including PKS, GKE and AKS clusters. The installation instructions are divided between the PKS installation, which uses OpenID Connect (OIDC) for authentication, and the install on other hosted Kubernetes clusters.

Prerequisites

Before you install Build Service, you must:

  • Ensure your Kubernetes cluster is configured with PersistentVolumes. Configure the cache size per image to 2 GB. 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.

  • Download the Duffle executable for your operating system from the Tanzu Build Service page on Tanzu Network.

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

Installing on TKG/GKE/AKS

Create a kubernetes cluster that you would like to install build service onto and target the cluster as follow:

kubectl config use-context <CLUSTER-NAME>

Create a Credentials File

Create a credentials file to provide the location of the local kubeconfig and the location of the TLS certificate credentials to duffle during the Build Service installation.

To create a credentials file:

  1. Navigate to the /tmp folder and create a file named credentials.yml.

  2. Add the properties shown in the example below to the credentials.yml file:

    name: build-service-credentials
credentials:
 - name: kube_config
   source:
     path: "PATH-TO-KUBECONFIG"
   destination:
     path: "/root/.kube/config"
 - name: ca_cert
   source:
     path: "PATH-TO-CA"
   destination:
     path: "/cnab/app/cert/ca.crt"

    Where:

    • PATH-TO-KUBECONFIG is the path to the kubeconfig configuration file on your local machine. This file is required to enable Build Service to interact with the target cluster.
    • 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. If the registry you are using is not internally deployed (eg. gcr, dockerhub), this can be set to "".

      Note: All local paths in the credentials file must be absolute.

Relocate Images to a Registry

This procedure relocates images from the Build Service bundle that you downloaded from Tanzu Network to an internal image registry.

Note: Keep in mind an image repository (for example, gcr.io/repository) is a location inside an image registry (for example, gcr.io).

To move the images from the Build Service bundle to an 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.

  2. Push the images to the image repository by running:

    duffle relocate -f /tmp/build-service-${version}.tgz -m /tmp/relocated.json -p IMAGE-REPOSITORY

    Note: When relocating to a harbor/gcr repository, the IMAGE-REGISTRY will need to be appended with the destination folder for the images, for example, IMAGE-REGISTRY/build-service-imgs.

    For example:

    • Dockerhub duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p my-dockerhub-repo
    • GCR duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p gcr.io/my-project/build-service
    • Artifactory duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p artifactory.com/my-project/build-service
    • Harbor duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p harbor.io/my-project/build-service

Run Duffle Install

Use Duffle to install Build Service and define the required Build Service parameters by running:

duffle install BUILD-SERVICE-INSTALLATION-NAME -c /tmp/credentials.yml  \
    --set kubernetes_env=CLUSTER-NAME \
    --set docker_registry=DOCKER-REGISTRY \
    --set docker_repository=DOCKER-REPOSITORY \
    --set registry_username="REGISTRY-USERNAME" \
    --set registry_password="REGISTRY-PASSWORD" \
    --set custom_builder_image="BUILDER-IMAGE-TAG" \
    -f /tmp/build-service-${version}.tgz \
    -m /tmp/relocated.json

Where:

  • BUILD-SERVICE-INSTALLATION-NAME is the name you give your Build Service installation.
  • CLUSTER-NAME is the name of the Kubernetes cluster where Build Service is installed.
  • DOCKER-REGISTRY is the domain of the image registry that you configured.

    Note: For Docker Hub, the domain must be index.docker.io. Do not include subpaths in the registry. gcr.io and acr.io are examples of valid fields for the registry.

  • DOCKER-REPOSITORY is the image repository where stack images and store buildpackages will be relocated.

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

  • 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: Secrets in Tanzu Build Service for more information about how the registry username and password are used in Tanzu Build Service.

  • BUILDER-IMAGE-TAG is the fully-qualified tag where Build Service will create a default cluster-wide builder.

    Note: Please provide the fully-qualified image tag. For example, if installing using Dockerhub, you would provide my-dockerhub-org/default-builder. If installing using GCR, you would provide gcr.io/my-project/build-service/default-builder.

Other optional parameters you can add using the --set 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 that should not use a proxy.

Installing on PKS

  • Install PKS v1.6 or later. For more information, see Installing Enterprise PKS in the PKS documentation.

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

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

Retrieve PKS Cluster Credentials

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

To retrieve the PKS cluster credentials:

  1. Log in to PKS and get the latest kubeconfig by running:

    pks get-kubeconfig CLUSTER-NAME -a API-URI -u USERNAME -p PASSWORD --ca-cert PATH-TO-CERTIFICATE

    Where:

    • API-URI is the PKS 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 PKS cluster where Build Service runs.

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

    For example:

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

Create a Credentials File

Create a credentials file to provide the location of the local kubeconfig and the location of the TLS certificate credentials to duffle during the Build Service installation.

To create a credentials file:

  1. Navigate to the /tmp folder and create a file named credentials.yml.

  2. Add the properties shown in the example below to the credentials.yml file:

    name: build-service-credentials
credentials:
 - name: kube_config
   source:
     path: "PATH-TO-KUBECONFIG"
   destination:
     path: "/root/.kube/config"
 - name: ca_cert
   source:
     path: "PATH-TO-CA"
   destination:
     path: "/cnab/app/cert/ca.crt"

    Where:

    • PATH-TO-KUBECONFIG is the path to the kubeconfig configuration file on your local machine. This file is required to enable Build Service to interact with the target cluster.
    • 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. If the registry you are using is not internally deployed (eg. gcr, dockerhub), this can be set to "".

      Note: All local paths in the credentials file must be absolute.

Relocate Images to a Registry

This procedure relocates images from the Build Service bundle that you downloaded from Tanzu Network to an internal image registry.

Note: Keep in mind an image repository (for example, gcr.io/repository) is a location inside an image registry (for example, gcr.io).

To move the images from the Build Service bundle to an 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.

  2. Push the images to the image repository by running:

    duffle relocate -f /tmp/build-service-${version}.tgz -m /tmp/relocated.json -p IMAGE-REPOSITORY

    Note: When relocating to a harbor/gcr repository, the IMAGE-REGISTRY will need to be appended with the destination folder for the images eg. IMAGE-REGISTRY/build-service-imgs

    For example:

    • Dockerhub duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p my-dockerhub-repo
    • GCR duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p gcr.io/my-project/build-service
    • Artifactory duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p artifactory.com/my-project/build-service
    • Harbor duffle relocate -f /tmp/build-service-0.2.0.tgz -m /tmp/relocated.json -p harbor.io/my-project/build-service

Run Duffle Install

Use Duffle to install Build Service and define the required Build Service parameters by running:

duffle install BUILD-SERVICE-INSTALLATION-NAME -c /tmp/credentials.yml  \
    --set kubernetes_env=CLUSTER-NAME \
    --set docker_registry=DOCKER-REGISTRY \
    --set docker_repository=DOCKER-REPOSITORY \
    --set registry_username=REGISTRY-USERNAME \
    --set registry_password=REGISTRY-PASSWORD \
    --set custom_builder_image=BUILDER-IMAGE-TAG \
    -f /tmp/build-service-${version}.tgz \
    -m /tmp/relocated.json

Where:

  • BUILD-SERVICE-INSTALLATION-NAME is the name you give your Build Service installation.
  • CLUSTER-NAME is the name of the Kubernetes cluster where Build Service is installed.
  • DOCKER-REGISTRY is the domain of the image registry that you configured.

    Note: For Docker Hub, the domain must be index.docker.io. Do not include subpaths in the registry. gcr.io and acr.io are examples of valid fields for the registry.

  • DOCKER-REPOSITORY is the image repository where stack images and store buildpackages will be relocated.

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

  • 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: See Secrets in Tanzu Build Service for more information about how the registry username and password are used in Tanzu Build Service.

  • BUILDER-IMAGE-TAG is the fully-qualified tag where Build Service will create a default cluster-wide builder.

    Note: Please provide the fully-qualified image tag. For example, if installing using Dockerhub, you would provide my-dockerhub-org/default-builder. If installing using GCR, you would provide gcr.io/my-project/build-service/default-builder.

Other optional parameters you can add using the --set flag:

  • oidc_username_prefix is the UAA OIDC Username Prefix (required if OIDC was configured for PKS).
  • oidc_group_prefix is the UAA OIDC Groups Prefix (required if OIDC was configured for PKS).
  • 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 that should not use a proxy.

Configuring PKS 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 PKS deployment to provide authentication for Build Service.

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

  1. Navigate to the OpsManager Installation Dashboard.

  2. Click the PKS 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.

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 custom cluster builders available in your installation:

    kp custom-cluster-builder 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     org.cloudfoundry.stacks.cflinuxfs3    <image@sha256:digest>
full       true     org.cloudfoundry.stacks.cflinuxfs3    <image@sha256:digest>
tiny       true     io.paketo.stacks.tiny                 <image@sha256:digest>

Updating Build Service Dependencies

Visit the Build Service dependencies tile on PivNet. Build Service can be updated with those artifacts both directly against the PivNet registry or via the downloaded versions of those images.

Online Update of Dependencies

If the kp CLI has access to pull images from the Pivnet Registry, the stack images and buildpacks used by build service can be updated using the following commands.

Stack Update

Update the stacks:

kp stack update default --build-image registry.pivotal.io/tbs-dependencies/build-full@sha256:<image-sha> --run-image registry.pivotal.io/tbs-dependencies/run-full@sha256:<image-sha>
kp stack update full --build-image registry.pivotal.io/tbs-dependencies/build-full@sha256:<image-sha> --run-image registry.pivotal.io/tbs-dependencies/run-full@sha256:<image-sha>
kp stack update tiny --build-image registry.pivotal.io/tbs-dependencies/build-tiny@sha256:<image-sha> --run-image registry.pivotal.io/tbs-dependencies/run-tiny@sha256:<image-sha>
kp stack update base --build-image registry.pivotal.io/tbs-dependencies/build-base@sha256:<image-sha> --run-image registry.pivotal.io/tbs-dependencies/run-base@sha256:<image-sha>

Note: Both build and run images need to be provided to update a stack

An updated stack can be viewed with the following command:

kp stack status <stack-name>

Store Update

Update a store:

kp store add <store-name> registry.pivotal.io/tbs-dependencies/<buildpack-name>:<buildpack-tag>

Additionally, multiple buildpacks can be added to Build Service by passing multiple image references

kp store add <store-name> registry.pivotal.io/tbs-dependencies/<buildpack1>:<buildpack1-tag> registry.pivotal.io/tbs-dependencies/<buildpack2>:<buildpack2-tag> registry.pivotal.io/tbs-dependencies/<buildpack3>:<buildpack3-tag>

To list the buildpacks now available in the store:

kp store status <store-name>

Offline Update of Dependencies

If the kp CLI cannot access the images in the Pivnet Registry, the stack images and buildpacks used by build service can be updated by first downloading those images and saving them locally. These files can be provided to the kp CLI to upload to build service.

Stack Update

Fetch the stack images into the docker daemon:

docker pull registry.pivotal.io/tbs-dependencies/build-full@sha256:<image-sha>
docker pull registry.pivotal.io/tbs-dependencies/run-full@sha256:<image-sha>

Save those images to disk:

docker save registry.pivotal.io/tbs-dependencies/build-full@sha256:<image-sha> > build.tar
docker save registry.pivotal.io/tbs-dependencies/run-full@sha256:<image-sha> > run.tar

Update the stack with the saved image:

kp stack update default --build-image build.tar --run-image run.tar --local

Note: Both build and run images need to be provided to update the stack.

The updated stack can be viewed with the following command:

kp stack status default

Store Update

Updating the Store offline with new buildpacks is not currently supported but will be in upcoming releases. To update the store, see Store Update.

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 stack status <stack-name>

To update the location of the run image:

  1. Using kubectl update the buildservice.pivotal.io/defaultRepository annotation on the build-service-stack Stack resource to a location that can be accessed publicly.
  2. Re-run kp stack update with the most recent build image and run image from the build-service-dependencies page.