Manage Builders of your Tanzu Build Service

This topic tells you how to manage Builders of your Tanzu Build Service (commonly known as TBS).

A Builder is a Tanzu Build Service resource used to manage Cloud Native Buildpack builders.

Builders contain a set of buildpacks and a stack used to create images.

There are two types of Builders:

Cluster Builders: Cluster-scoped Builders
Builders: Namespace-scoped Builders

Note: Only Build Service Admins can manage Cluster Builders.

The kp CLI can be used to manage builders and clusterbuilders. The help text is published in the kpack-cli documentation on GitHub.

$ kp builder
Builder Commands

Usage:
  kp builder [command]

Aliases:
  builder, builders, bldrs, bldr

Available Commands:
  create      Create a builder
  delete      Delete a builder
  list        List available builders
  patch       Patch an existing builder configuration
  save        Create or patch a builder
  status      Display status of a builder

Flags:
  -h, --help   help for builder

Use "kp builder [command] --help" for more information about a command.

$ kp clusterbuilder
ClusterBuilder Commands

Usage:
  kp clusterbuilder [command]

Aliases:
  clusterbuilder, clusterbuilders, clstrbldrs, clstrbldr, cbldrs, cbldr, cbs, cb

Available Commands:
  create      Create a cluster builder
  delete      Delete a cluster builder
  list        List available cluster builders
  patch       Patch an existing cluster builder configuration
  save        Create or patch a cluster builder
  status      Display cluster builder status

Flags:
  -h, --help   help for clusterbuilder

Note: These docs assume you are using kp CLI v0.10.x with Tanzu Build Service v1.10.x. If a feature is not working, you might need to upgrade your CLI.

Creating a Builder

Use the kp cli to create a Builder:

Cluster Builder:

kp clusterbuilder create <name> --tag <tag> --order <order> --stack <stack> --store <store>

kp clusterbuilder create <name> --tag <tag> --stack <stack> --store <store> --buildpack <buildpack>

Builder:

kp builder create <name> --tag <tag> --order <order> --stack <stack> --store <store> --namespace <namespace>

kp builder create <name> --tag <tag> --stack <stack> --store <store> --namespace <namespace> --buildpack <buildpack>

Where:

name: The name of the builder.
tag: The registry location where the builder is created.
stack: The name of the stack used by the builder.
store: The name of the store containing the buildpacks used by the builder.
namespace The kubernetes namespace for the builder (for Builders only).
order: The local path to the buildpack order YAML that the builder uses. Sample order YAML files are available on the VMware Tanzu Build Service Dependencies page on Tanzu Network. For more information about listing buildpacks in groups in the order YAML, see builder.toml in the Buildpacks.io documentation.

Example order YAML file that used by a builder designed to build NodeJS and Java apps:
```
- group:
- id: tanzu-buildpacks/nodejs
- group:
- id: tanzu-buildpacks/java
```
buildpack: Buildpack id and optional version in the form of either ‘ @ ’ or ‘ ’. Repeat for each buildpack in order, or supply once with comma-separated list. This cannot be combined with --order. All supplied buildpacks are in the same group.

Patching a builder

You can update a builder resource using the kp cli. To update a builder given a name, run:

Cluster Builder:

kp clusterbuilder patch <name> --order <order> --stack <stack> --store <store>

kp clusterbuilder patch <name> --stack <stack> --store <store> --buildpack <buildpack>

Builder:

kp builder patch <name> --order <order> --stack <stack> --store <store> --namespace <namespace>

kp builder patch <name> --stack <stack> --store <store> --namespace <namespace> --buildpack <buildpack>

kp ccb patch and kp cb patch are respective aliases.

Where:

name: The name of the builder.
stack: The name of the stack used by the builder.
store: The name of the store containing the buildpacks used by the builder.
namespace The Kubernetes namespace for the builder (for Builders only).
order: The local path to the buildpack order YAML that the builder uses. Sample order YAML files are available on the VMware Tanzu Build Service Dependencies page on Tanzu Network. For more information about listing buildpacks in groups in the order YAML, see builder.toml in the Buildpacks.io documentation.

Example order YAML file used by a builder designed to build NodeJS and Java apps:
```
---
- group:
- id: paketo-buildpacks/bellsoft-liberica
- id: paketo-buildpacks/gradle
- group:
- id: paketo-buildpacks/nodejs
```
buildpack: Buildpack ID and optional version in the form of either ‘ @ ’ or ‘ ’. Repeat for each buildpack in order, or supply once with comma-separated list. This cannot be combined with --order. All supplied buildpacks are in the same group.

Note: The tag (location in a registry) of a builder cannot be modified. To change this field, you must create a new builder.

Saving Builders

Users can create or update a Builder/ClusterBuilder by using the save command. The kp builder/clusterbuilder save command is used exactly the same as kp builder/clusterbuilder create and kp builder/clusterbuilder update, but it determines whether a builder/clusterbuilder needs to be created or updated.

To save a Builder/ClusterBuilder:

Cluster Builder:

kp clusterbuilder save <name> --tag <tag> --order <order> --stack <stack> --store <store>

kp clusterbuilder save <name> --tag <tag> --stack <stack> --store <store> --buildpack <buildpack>

Builder:

kp builder save <name> --tag <tag> --order <order> --stack <stack> --store <store> --namespace <namespace>

kp builder save <name> --tag <tag> --stack <stack> --store <store> --namespace <namespace> --buildpack <buildpack>

Where:

name: The name of the builder.
tag: The registry location where the builder is created.
stack: The name of the stack used by the builder.
store: The name of the store containing the buildpacks used by the builder.
namespace The Kubernetes namespace for the builder (for Builders only).
order: The local path to the buildpack order YAML that the builder uses. Sample order YAML files are available on the VMware Tanzu Build Service Dependencies page on Tanzu Network. For more information about listing buildpacks in groups in the order YAML, see builder.toml in the Buildpacks.io documentation.

Example order YAML file used by a builder designed to build NodeJS and Java apps:
```
---
- group:
- id: paketo-buildpacks/bellsoft-liberica
- id: paketo-buildpacks/gradle
- group:
- id: paketo-buildpacks/nodejs
```
buildpack: Buildpack ID and optional version in the form of either ‘ @ ’ or ‘ ’. Repeat for each buildpack in order, or supply once with comma-separated list. This cannot be combined with --order. All supplied buildpacks are in the same group.

Deleting Builders

To delete a builder:

Cluster Builder:

kp clusterbuilder delete <builder name>

Builder:

kp builder delete <builder name> --namespace <namespace>

Warning: Deleting a builder prevents image configs that reference that builder from successfully building again.

Retrieving Builder Details

To get builder details:

Cluster Builder:

kp clusterbuilder status <builder-name>

Builder:

kp builder status <builder-name> --namespace <namespace>

Example:

$ kp clusterbuilder status tiny

Status:       Ready
Image:        gcr.io/my-repo/tiny@sha256:07d94db2e3e9f43cba67c389f1c83e4eac821aa83084a88136ed8d431b37f008
Stack:        io.paketo.stacks.tiny
Run Image:    gcr.io/cf-build-service-dev-219913/ssuresh/install/run@sha256:e9159f0ef23c28b943cfb1b5d5be9638b67211f6ff0bd3fae35ff4b499136152

BUILDPACK ID                                  VERSION    HOMEPAGE
paketo-buildpacks/graalvm                     4.0.0      https://github.com/paketo-buildpacks/graalvm
tanzu-buildpacks/go-dist                      0.1.3
paketo-buildpacks/gradle                      3.5.0      https://github.com/paketo-buildpacks/gradle
paketo-buildpacks/sbt                         3.6.0      https://github.com/paketo-buildpacks/sbt
paketo-buildpacks/maven                       3.2.1      https://github.com/paketo-buildpacks/maven
tanzu-buildpacks/dep                          0.0.10
paketo-buildpacks/spring-boot                 3.5.0      https://github.com/paketo-buildpacks/spring-boot
paketo-buildpacks/leiningen                   1.2.1      https://github.com/paketo-buildpacks/leiningen
paketo-buildpacks/spring-boot-native-image    2.0.0      https://github.com/paketo-buildpacks/spring-boot-native-image
paketo-buildpacks/executable-jar              3.1.3      https://github.com/paketo-buildpacks/executable-jar
tanzu-buildpacks/go-build                     0.0.23
paketo-buildpacks/environment-variables       2.1.2      https://github.com/paketo-buildpacks/environment-variables
paketo-buildpacks/procfile                    3.0.0      https://github.com/paketo-buildpacks/procfile
paketo-buildpacks/image-labels                2.0.6      https://github.com/paketo-buildpacks/image-labels
tanzu-buildpacks/dep-ensure                   0.0.29
tanzu-buildpacks/go-mod-vendor                0.0.26
tanzu-buildpacks/java-native-image            3.10.0     https://github.com/pivotal-cf/tanzu-java-native-image
tanzu-buildpacks/go                           1.0.9


DETECTION ORDER
Group #1
  tanzu-buildpacks/[email protected]
Group #2
  tanzu-buildpacks/[email protected]
Group #3
  paketo-buildpacks/[email protected]

Listing Builders

To list all builders available to the current user:

Cluster Builder:
```
kp clusterbuilder list
```

Builder:

kp builder list --namespace <namespace>

Corresponding kpack Resources

All Build Service Builders are represented as kpack resources.

Pinning Buildpack versions

You can pin buildpack versions by specifying the version for buildpacks in the order file.

As an example, consider the clusterbuilder created below:

kp cb create pinned \
  --tag my-registry.io/example/pinned \
  --order order.yaml

Where the contents of order.yaml file is:

- group:
  - id: tanzu-buildpacks/php
    version: 0.0.5
- group:
  - id: tanzu-buildpacks/nodejs
    version: 1.3.0

Note: When a buildpack version is pinned, Images that use the Builder do not initiate new Builds due to new Buildpack versions. As a best practice, only pin a buildpack version when necessary.

Update Lifecycle

All builders make use of a lifecycle. A lifecycle orchestrates buildpack execution, then assembles the resulting artifacts into a final app image. Within Build Service, it is uploaded to the canonical registry, which is the docker-repository specified during Tanzu Build Service install. More information on lifecycles can be found in Lifecycle on the Buildpacks.io website.

To update the lifecycle to be used by builders:

```
kp lifecycle update --image <image-tag>
```

Note: You must have credentials to access the registry on your machine.