Managing Builders

Page last updated:

Note: Only Build Service Admins can manage Cluster scoped builders.

Builder Configurations

To create a builder with the pb cli, you must create a builder configuration YAML that includes the following properties:

  • name: The name of the builder.

  • tag: The registry location where the builder is created.

  • scope: Defines whether the builder is available to the all users in the cluster or to users of the currently targeted project. One of ‘Cluster’ or 'Project’.

  • order: The buildpack order that the builder uses. For more information about listing buildpacks in groups, see builder.toml in the Buildpacks.io documentation.

Note: Build Service must have the appropriate credentials to push to tag. Build Service has access to the registry used at install time and any secrets attached to the current project.

Applying Builder Configurations

To apply a builder configuration to Build Service:

  1. Create a builder configuration YAML file. For example:

    name: foo
    tag: REGISTRY-DOMAIN/PATH-TO-NEW-BUILDER
    scope: Project OR Cluster
    order:
    - group:
      -  id: org.cloudfoundry.node-engine
      -  id: org.cloudfoundry.npm
    

    Note: Using the pb store list --order can be useful for this task as the command returns buildpacks available for use in builders in correct order definition.

  2. Apply the builder configuration by running:

    pb builder apply -f PATH-TO-BUILDER-CONFIGURATION
    

    Where PATH-TO-BUILDER-CONFIGURATION is the local path where you saved the builder configuration YAML file.

    Note: When the scope is Project the builder will be applied to the currently targeted project.

Deleting Builders

To delete a builder:

  • Delete a cluster scoped builder:

    pb builder delete <builder name> --cluster
    
  • Delete a project scoped builder:

    pb builder delete <builder name>
    

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

Retrieving Builder Details

To get builder details:

  • Details for a cluster scoped builder:

    pb builder get <builder name> --cluster
    
  • Details for a project scoped builder:

    pb builder get <builder name>
    

Listing Builders

To list all builders available to the current user:

pb builder list

Retrieving Builder Status

To get the current builder status:

  • Status for a cluster scoped builder:

    pb builder status <builder name> --cluster
    
  • Status for a project scoped builder:

    pb builder status <builder name>
    

Corresponding kpack Resources

All Build Service builders are represented as kpack resources.

Project Scoped builders utilize the CustomBuilder resource. Cluster Scoped builders utilize the CustomClusterBuilder resource.