Managing Builders

Page last updated:

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

Custom Builders contain a set of buildpacks and a stack that will be used to create images.

There are two types of Custom Builders:

  • Custom Cluster Builders: Cluster-scoped Builders
  • Custom Builders: Namespace-scoped Builders

Note: Only Build Service Admins can manage Custom Cluster Builders.

Creating a Custom Builder

Use the kp cli to create a Custom Builder:

  • Custom Cluster Builder:

    kp custom-cluster-builder create <name> <tag> --order <order> --stack <stack> --store <store>
    
  • Cluster Builder:

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

kp ccb create and kp cb create are respective aliases.

Where:

  • name: The name of the builder.
  • tag: The registry location where the builder will be created.
  • stack: The name of the stack to be used by the builder.
  • store: The name of the store containing the buildpacks that will be used by the builder.
  • namespace The kubernetes namespace for the builder (for Custom Builders only)
  • order: The local path to the buildpack order YAML that the builder will use. Sample order YAML files will be 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 would be 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

Patching a Custom Builder

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

  • Custom Cluster Builder:

    kp custom-cluster-builder patch <name> --order <order> --stack <stack> --store <store>
    
  • Cluster Builder:

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

kp ccb patch and kp cb patch are respective aliases.

Where:

  • name: The name of the builder.
  • stack: The name of the stack to be used by the builder.
  • store: The name of the store containing the buildpacks that will be used by the builder.
  • namespace The kubernetes namespace for the builder (for Custom Builders only)
  • order: The local path to the buildpack order YAML that the builder will use. Sample order YAML files will be 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 would be 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

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

Deleting Builders

To delete a Custom Builder:

  • Custom Cluster Builder:

    kp custom-cluster-builder delete <builder name>
    
  • Custom Builder:

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

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

Retrieving Builder Details

To get builder details:

  • Custom Cluster Builder:

    kp custom-cluster-builder status <builder-name>
    
  • Custom Builder:

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

Listing Builders

To list all builders available to the current user:

  • Custom Cluster Builder:

    kp custom-cluster-builder list
    
  • Custom Builder:

    kp custom-builder list --namespace <namespace>
    

Corresponding kpack Resources

All Build Service Custom Builders are represented as kpack resources.