Installing and Configuring kpack Only

Page last updated:

This topic describes how to install and configure 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:

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

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:

  1. Run:

    pks get-credentials CLUSTER-NAME
    

    Where CLUSTER-NAME is the name of the PKS cluster where Build Service runs.

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

Create a Credentials File

Create a credentials file to provide the location of the TLS certificate credentials to duffle during Build Service installation.

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.
    • 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 Parameters and Annotations

To define custom parameters, you must create a JSON file that defines the parameters.

Note: If you create the parameters file, you can provide it while running the Duffle install command using the -p flag in place of the --set options described in Install Build Service as a kpack-Only Installation.

To create this JSON file:

  1. Navigate to the /tmp folder and create a file named parameters.json.

  2. 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.
  3. Add any of these properties to the /tmp/parameters.json file:

    • 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.
    • ingress_annotations: Configures ingress annotations.
    • replica_count: Defines the number of Build Service instances running. The default value is 1.
    • no_gateway: Installs the Pivotal Builder and kpack, the Build Service CRDs, and controllers. This is a boolean value that defaults to false.
    • 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.

      Warning: If you set no_gateway to true, you can only interact with Build Service through kubectl. For more information, see Install Build Service as a kpack-Only Installation.

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 Build Service

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

Install Build Service as a kpack-Only Installation

This procedure describes how to install Build Service as a kpack-only installation.

Warning: If you install a kpack-only installation, you can only interact with Build Service through kubectl.

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

To install Build Service as a kpack-only installation:

  1. Remove these properties from the credentials.yml file that you created as part of Create a Credentials File:

    • tls_cert
    • tls_key
  2. Create a parameters.json file and set the no_gateway property in the file to true. This installs the Pivotal Builder, Build Service CRDs, and their controllers. For more information, see (Optional) Define Custom Parameters and Annotations.

  3. 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="" \
        --set kubernetes_env=PKS-CLUSTER-NAME \
        --set docker_registry=IMAGE-REGISTRY \
        --set registry_username="REGISTRY-USERNAME" \
        --set registry_password="REGISTRY-PASSWORD" \
        --set 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.
    • 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.