Installing and Configuring kpack Only

Page last updated:

This topic describes how to install and configure a kpack-only deployment of Pivotal Build Service.

Overview

To install Build Service, you must configure UAA, credentials, and TLS certificates, and you must 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 do a kpack-only installation. In a kpack-only installation, all interaction with Build Service can be done through the kubectl CLI only.

For a standard Build Service installation, see Installing and Configuring Build Service.

Prerequisites

Before you install Build Service, you must:

• Create or use an existing Kubernetes cluster.

• Install Enterprise Pivotal Container Service (PKS) v1.5 or later. For more information, see Installing Enterprise PKS in the PKS documentation.

• 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. 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.

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

Configure kpack

The procedures in this section describe how to configure kpack to prepare for installation.

Create a Credentials File

Note: Ensure that the kubectl CLI has access to the Kubernetes cluster.

To create a credentials file:

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

2. Add these properties 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 Certificate Authority (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.

Move Images to an Image Registry

This procedure describes how to relocate images from the Build Service bundle that you downloaded from Pivotal Network to an internal image registry.

To move the images from the Build Service bundle to an internal 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 registry by running:

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

Install kpack

The procedures in this section describe how to use Duffle to define the required kpack parameters and install kpack.

For more information about kpack, see the kpack repository on GitHub.

To install Build Service as a kpack-only installation:

1. Use Duffle to define the required kpack parameters and install kpack by running:

   duffle install BUILD-SERVICE-INSTALLATION-NAME -c /tmp/credentials.yml  \
       --set 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="" \
       --set no_gateway=true \
       -f /tmp/build-service-${version}.tgz \
       -m /tmp/relocated.json
   

   Where:

   • BUILD-SERVICE-INSTALLATION-NAME is the name you give your Build Service installation.
   • 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.
     
     Other optional parameters you may add using --set:
   • 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.