Installing and Configuring Pivotal Build Service
Page last updated:
This topic describes how to install and configure Pivotal Build Service.
Overview
To install Build Service, you must configure a User Account and Authentication (UAA) client, credentials, and TLS certificates. You must then relocate images to an internal image registry. You can also define optional parameters and annotations during installation.
The procedures in this topic describe how to install and configure a standard Build Service installation. For a kpack-only installation, see Installing and Configuring kpack Only.
Prerequisites
Before you install Build Service, you must:
Install Enterprise Pivotal Container Service (PKS) v1.5 or later. For more information, see Installing Enterprise PKS in the PKS documentation.
Install Ruby. Ruby is required to create a UAA client.
Install an ingress controller on the Kubernetes cluster where you install Build Service. The Build Service expects an ingress controller and an ingress service to configure its own ingress. For more information, see How to set up an Ingress Controller for a PKS cluster in the Pivotal Knowledge Base.
Install the Kubernetes command-line tool,
kubectl
. For more information, see Install and Set Up Kubectl.Note: Kubectl is only required if you do not have an ingress controller installed locally.
Configure
PersistentVolumes
on the Kubernetes cluster where you install Build Service. Configure the cache size per image to 2 GB. Build Service requiresPersistentVolumeClaims
to cache build artifacts, which reduces the time of subsequent builds. Persistent volume constrains the number of images that can exist on a Kubernetes cluster. If each image claims 2 GB and you allocate 100 GB in persistent volume, Build Service can build, monitor, and execute rebuilds for 50 images at a time. For testing the Alpha release, 20 GB to 30 GB of persistent volume is sufficient. Pivotal recommends at least 100 GB for more serious usage. For more information, see Persistent Volumes in the Kubernetes documentation.Download the Duffle executable for your operating system from the Pivotal Build Service page on Pivotal Network.
Install Docker on the machine that is running Duffle.
Download the Build Service Bundle from the Pivotal Build Service page on Pivotal Network.
Configure UAA as an OIDC Provider for PKS
The authorization process for Build Service uses a combination of RBAC rules and UAA authentication. To enable this authorization flow, you must configure UAA as an OpenID Connect (OIDC) provider for your PKS deployment.
To configure UAA as an OIDC provider for your PKS deployment:
Navigate to the Ops Manager 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. You use these values when you install Duffle.
Click Save.
In the Ops Manager Installation Dashboard, click Review Pending Changes, then Apply Changes.
Configure Build Service
The procedures in this section describe how to configure Build Service to prepare for installation.
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:
Run:
pks get-credentials CLUSTER-NAME
Where
CLUSTER-NAME
is the name of the PKS cluster where Build Service runs.Target the PKS cluster by running:
kubectl config use-context CLUSTER-NAME
Where
CLUSTER-NAME
is the name of the PKS cluster where Build Service runs.
User Management
Build Service uses the UAA instance for your PKS deployment to authenticate users. For more information about creating users, see Create a UAA User for Build Service.
Configure TLS Certificate
You must create a TLS certificate for the Build Service domain or use an existing certificate. This certificate may be self-signed.
To configure a TLS certificate for Build Service:
Create or use an existing TLS certificate for the Build Service domain. For more information, see Configuring SSL Certificates in the BOSH documentation.
Note: If you use a self-signed certificate, add the
--skip-ssl-validation
flag.If you are using Mac OS, add the Certificate Authority (CA) certificate for the TLS certificate to the keychain. Update the trust settings from Use System Defaults to Always Trust through the OS X keychain.
Record the local paths to the
.crt
and.key
files for the TLS certificate.
Create a Credentials File
Create a credentials file to provide 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" - name: tls_cert source: path: "PATH-TO-TLS-CERTIFICATE" destination: path: "/cnab/app/cert/tls.crt" - name: tls_key source: path: "PATH-TO-TLS-PRIVATE-KEY" destination: path: "/cnab/app/cert/tls.key"
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.PATH-TO-TLS-CERTIFICATE
is the path to the TLS certificate. This TLS certificate is required for authenticated communication between thepb
CLI and Build Service. The CA for this TLS certificate must be trusted by the workstation communicating with Build Service.PATH-TO-TLS-PRIVATE-KEY
is the path to the private key corresponding to the TLS certificate.Note: All local paths in the credentials file must be absolute.
(Optional) Define Custom Ingress Annotations
This section describes how to create a parameters file to provide ingress annotations to the Build Service during installation.
By default, Build Service uses the NGINX ingress controller, and you do not have to use any annotations. However, providing custom ingress annotations allows you to use different ingress controllers.
To define custom ingress annotations for Build Service, you must create a JSON file that defines the annotations. To create this JSON file:
Note: If you create the parameters file, you can provide it while running the Duffle install command using the -p
flag.
Navigate to the
/tmp
folder and create a file namedparameters.json
.Add the
ingress_annotations
property to the/tmp/parameters.json
file:{ "ingress_annotations": { "kubernetes.io/ingress.ANNOTATION-KEY": "ANNOTATION-VALUE", "kubernetes.io/ingress.ANOTHER-ANNOTATION-KEY": "ANOTHER-ANNOTATION-VALUE" } }
Where:
ANNOTATION-KEY
is a key you define for the first annotation.ANNOTATION-VALUE
is the value you define for the first annotation.ANOTHER-ANNOTATION-KEY
is a key you define for the second annotation.ANOTHER-ANNOTATION-VALUE
is the value you define for the second annotation.
Move Images to an Image Registry
This procedure relocates images from the Build Service bundle that you downloaded from Pivotal Network to an internal image registry.
Note: The image in the Build Service image bundle named run-image
provides the runtime environment in the form of an image. You must relocate this image to a public registry location.
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
Install Build Service
The procedures in these sections describe how to use Duffle to define the required Build Service parameters and install Build Service.
Install Build Service
This procedure describes how to do a standard Build Service installation.
To install Build Service so that all interactions with Build Service must be made through kubectl
,
see Installing and Configuring kpack Only.
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 domain=BUILD-SERVICE-DOMAIN \ --set kubernetes_env=PKS-CLUSTER-NAME \ --set docker_registry=IMAGE-REGISTRY \ --set registry_username="REGISTRY-USERNAME" \ --set registry_password="REGISTRY-PASSWORD" \ --set uaa_url=UAA-URL \ -f /tmp/build-service-${version}.tgz \ -m /tmp/relocated.json
Where:
BUILD-SERVICE-INSTALLATION-NAME
is the name you give your Build Service installation.BUILD-SERVICE-DOMAIN
is the domain name used to target Build Service. You configured this domain as the domain for the ingress controller.PKS-CLUSTER-NAME
is the name of the PKS cluster where Build Service is installed.IMAGE-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.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.UAA-URL
is the URL to access UAA.Note: If the values you recorded during Configure UAA as an OIDC Provider for PKS are different from the values in
oidc:
, add the--uaa_username_prefix="VALUE-SAVED"
flag to theduffle install
commandNote: If you defined custom ingress annotations during (Optional) Define Custom Ingress Annotations, include them with the
Other optional parameters you can add using the-p /tmp/parameters.json
flag.--set
flag:disable_builder_polling
: If set totrue
, this property prevents Build Service from polling builder images for buildpack updates. By default, this property is set tofalse
. If you setdisable_builder_polling
totrue
, you must configure a builder webhook. For more information, see Setting Up Builder Webhooks.replica_count
: Defines the number of Build Service instances running. The default value is1
.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.
Create a UAA User for Build Service
To access Build Service, you must configure one or more UAA users using the uaac
CLI.
Note: It is not required to create new users if PKS UAA is already integrated with LDAP/SAML and can leverage IDP users.
To create a UAA user for Build Service:
Install
uaac
by running:gem install cf-uaac
Target the UAA that you use to authenticate Build Service users by running:
uaac target UAA-URL --skip-ssl-validation
Where
UAA-URL
is the URL of the UAA that authenticates Build Service users.In the PKS tile, select the Credentials tab and record the credential for Pks Uaa Management Admin Client.
Log in as the admin client with the password you recorded in the previous step by running:
uaac token client get admin -s ADMIN-CLIENT-SECRET
Where
ADMIN-CLIENT-SECRET
is the credential for Pks Uaa Management Admin Client.Create a user by running:
uaac user add USER-USERNAME -p USER-PASSWORD --emails USER-EMAIL
Where:
USER-USERNAME
is a username for the new user.USER-PASSWORD
is a password for the new user.USER-EMAIL
is the email address of the new user.
Verify Installation
Verify your Build Service installation by logging in to Build Service with the UAA user credentials that you created.
To verify your Build Service installation:
Download the
pb
binary from the Pivotal Build Service page on Pivotal Network.Target the Build Service installation by running:
pb api set BUILD-SERVICE-DOMAIN
Where
BUILD-SERVICE-DOMAIN
is the domain for your Build Service installation.Note: If the UAA for Build Service uses a self-signed CA certificate, add the
--skip-ssl-validation
flag at the end of the command.Log in to Build Service with the user that you created as part of Create a UAA User for Build Service by running:
pb login
(Optional) Remove TLS Certificate
After you verify your Build Service installation, you can delete the .crt
and .key
files
for the TLS certificate that you created in Create TLS Certificate.