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 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.
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 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:
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 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
- 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 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 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 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:
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 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
- 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 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 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.
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:
Navigate to the OpsManager Installation Dashboard.
Click the PKS tile.
Select UAA.
Under Configure created clusters to use UAA as the OIDC provider, select Enable.
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.Click Save.
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:
Download the
kp
binary from the Tanzu Build Service page on Tanzu Network.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:
- Using
kubectl
update thebuildservice.pivotal.io/defaultRepository
annotation on thebuild-service-stack
Stack resource to a location that can be accessed publicly. - Re-run
kp stack update
with the most recent build image and run image from the build-service-dependencies page.