Installing and Configuring Pivotal Build Service

Overview
Prerequisites
Configure UAA as an OIDC Provider for PKS
Configure Build Service
Install Build Service
- Install Build Service
Create a UAA User for Build Service
Verify Installation
(Optional) Remove TLS Certificate

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 requires PersistentVolumeClaims 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 named credentials.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 the pb 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 named parameters.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 and acr.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 the duffle install command
  
  Note: If you defined custom ingress annotations during (Optional) Define Custom Ingress Annotations, include them with the -p /tmp/parameters.json flag.
  Other optional parameters you can add using the --set flag:
- disable_builder_polling: If set to true, this property prevents Build Service from polling builder images for buildpack updates. By default, this property is set to false. If you set disable_builder_polling to true, 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 is 1.
- 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.

Create a pull request or raise an issue on the source for this page in GitHub