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 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 utilizesPersistentVolumeClaims
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.
Download the Build Service Dependencies from the Tanzu Build Service Dependencies 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:
Navigate to the
/tmp
folder and create a file namedcredentials.yml
.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 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.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.
To move the images from the Build Service bundle to an internal image registry:
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.Push the images to the image registry by running:
duffle relocate -f /tmp/build-service-${version}.tgz -m /tmp/relocated.json -p IMAGE-REGISTRY
Note: When relocating to a harbor/gcr registry, 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.1.0.tgz -m /tmp/relocated.json -p my-dockerhub-repo
- GCR
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p gcr.io/my-project/build-service
- Artifactory
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p artifactory.com/my-project/build-service
- Harbor
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p harbor.io/my-project/build-service
- Dockerhub
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
andacr.io
are examples of valid fields for the registry.DOCKER-REPOSITORY
is the image registry where stack images and store buildpackages will be relocated.Note: This is identical to the IMAGE_REGISTRY 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 providegcr.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:
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:
Navigate to the
/tmp
folder and create a file namedcredentials.yml
.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 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.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.
To move the images from the Build Service bundle to an internal image registry:
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.Push the images to the image registry by running:
duffle relocate -f /tmp/build-service-${version}.tgz -m /tmp/relocated.json -p IMAGE-REGISTRY
Note: When relocating to a harbor/gcr registry, 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.1.0.tgz -m /tmp/relocated.json -p my-dockerhub-repo
- GCR
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p gcr.io/my-project/build-service
- Artifactory
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p artifactory.com/my-project/build-service
- Harbor
duffle relocate -f /tmp/build-service-0.1.0.tgz -m /tmp/relocated.json -p harbor.io/my-project/build-service
- Dockerhub
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
andacr.io
are examples of valid fields for the registry.DOCKER-REPOSITORY
is the image registry where stack images and store buildpackages will be relocated.Note: This is identical to the IMAGE_REGISTRY 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 providegcr.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.
Verify Installation
Verify your Build Service installation by first targeting the cluster Build Service has been installed on.
To verify your Build Service installation:
Download the
pb
binary from the Tanzu Build Service page on Tanzu Network.List the builders available in your installation:
pb builder list
You should see an output that looks as follows:
Cluster Builders
----------------
default
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 pb
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 stack:
pb stack update --build-image registry.pivotal.io/tbs-dependencies/build@sha256:<image-sha> --run-image registry.pivotal.io/tbs-dependencies/run@sha256:<image-sha>
Note: Both build and run images need to be provided to update the stack
The updated stack can be viewed with the following command:
pb stack status
Store Update
Update the store:
pb store add registry.pivotal.io/tbs-dependencies/<buildpack-name>:<buildpack-tag>
Additionally, multiple buildpacks can be added to Build Service by passing multiple image references
pb store add 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 to build service:
pb store list
Offline update of Dependencies
If the pb
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 as .tar
files. These file can be provided to the pb
CLI to upload to build service.
Stack Update
Fetch the stack images into the docker daemon:
docker pull registry.pivotal.io/tbs-dependencies/build@sha256:<image-sha>
docker pull registry.pivotal.io/tbs-dependencies/run@sha256:<image-sha>
Save those images to disk:
docker save registry.pivotal.io/tbs-dependencies/build@sha256:<image-sha> > build.tar
docker save registry.pivotal.io/tbs-dependencies/run@sha256:<image-sha> > run.tar
Update the stack with the saved image:
pb stack update --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:
pb stack status
Store Update
Fetch the buildpack images into the docker daemon:
docker pull registry.pivotal.io/tbs-dependencies/<buildpack1>:<buildpack1-tag>
docker pull registry.pivotal.io/tbs-dependencies/<buildpack2:<buildpack2-tag>
Save those images to disk:
docker save registry.pivotal.io/tbs-dependencies/<buildpack1>:<buildpack1-tag> > buildpack1.tar
docker save registry.pivotal.io/tbs-dependencies/<buildpack2>:<buildpack2-tag> > buildpack2.tar
Update the store with the previously saved images:
pb store add buildpack1.tar --local
Additionally, multiple buildpacks can be added to Build Service by passing multiple image references
pb store add buildpack1.tar buildpack2.tar --local
To list the buildpacks now available to build service:
pb store list
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:
pb stack status
To update the the location of the run image:
- Using
kubectl
update thebuildservice.pivotal.io/defaultRepository
annotation on thebuild-service-stack
Stack resource to a location that can be accessed publicly. - Re-run
pb stack update
with the most recent build image and run image from the build-service-dependencies page.