Managing ClusterStacks

Page last updated:

A ClusterStack is a cluster scoped resource that provides the build and run images for the Cloud Native Buildpack stack that will be used in a Builder.

Most users automatically configure three ClusterStack resources via the TBS installation process. These ClusterStacks are referenced in three corresponding ClusterBuilder resources.

Additional information about security and patching cadence for these stacks and their ideal use cases can be found here. More detailed release notes for the stacks can be accessed by following the links in the table below.

Name ID
tiny io.paketo.stacks.tiny
base io.buildpacks.stacks.bionic
full io.buildpacks.stacks.bionic

The kp CLI can be used to manage clusterstack. The help text is published here.

$ kp clusterstack
Cluster Stack Commands

Usage:
  kp clusterstack [command]

Aliases:
  clusterstack, csk

Available Commands:
  create      Create a cluster stack
  delete      Delete a cluster stack
  list        List cluster stacks
  save        Create or update a cluster stack
  status      Display cluster stack status
  update      Update a cluster stack

Flags:
  -h, --help   help for clusterstack

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

Note: These docs assume kp cli v0.2.* from TBS release v1.1.*. If a feature is not working, you may need to upgrade your cli.

Note: Only Build Service Admins (i.e. users with the pb-admin-role kubernetes ClusterRole) can perform clusterstack commands.

Create a ClusterStack

Users can create a clusterstack using build and run images from a Docker registry or the local machine. The run and build images provided during clusterstack creation will be uploaded to the canonical repository, which is the docker-repository specified during TBS install.

  • If using a Docker registry for the stack images:

    kp clusterstack create <clusterstack-name> \
     --build-image <location of build-image> \
     --run-image <location of run-image>
    

    Note: The user must have read access to the source Docker registry and write access to the canonical registry on the local machine.

    Example:

    kp csk create my-clusterstack \
     -b gcr.io/test/stack/run:latest
     -r gcr.io/test/stack/build:latest
    
  • If using local stack images created with docker save:

    kp clusterstack create <clusterstack-name> \
     --build-image <path to build-image>.tar \
     --run-image <path to run-image>.tar
    

    Note: The user must have write access to the canonical registry on the local machine.

    Example:

    kp csk create my-clusterstack \
      -b ./local-build-image.tar \
      -r ./local-run-image.tar
    

Update a ClusterStack

Users can update a stack using build and run images from a Docker registry or the local machine. The run and build images provided during clusterstack update will be uploaded to the canonical repository, which is the docker-repository specified during TBS install.

  • If using a Docker registry:

    kp clusterstack update <stack-name> \
     --build-image <location of build-image> \
     --run-image <location of run-image>
    

    Note: The user must have read access to the source Docker registry and write access to the canonical registry on the local machine.

    Example:

    kp csk update my-clusterstack \
     -b gcr.io/test/stack/run:latest
     -r gcr.io/test/stack/build:latest
    
  • If using local stack images created with docker save:

    kp clusterstack update <stack-name> \
     --build-image <path to build-image>.tar \
     --run-image <path to run-image>.tar
    

    Note: The user must have write access to the canonical registry on the local machine.

    Example:

    kp csk update my-clusterstack \
      -b ./local-build-image.tar \
      -r ./local-run-image.tar
    

Save a ClusterStack

Users can create or update a ClusterStack using the save command. The kp clusterstack save command is used exactly the same as kp clusterstack create and kp clusterstack update, but it will determine if a clusterstack needs to be created or updated.

Get ClusterStack Status

Users can get the current status of a clusterstack:

kp clusterstack status <stack-name>

The following is an example of the output for this command:

Status:          Ready
ID:             org.cloudfoundry.stacks.cflinuxfs3
Run Image:      paketo/run:full-cnb
Build Image:    paketo/build:full-cnb

Delete a ClusterStack

Users can delete an existing clusterstack:

kp clusterstack delete <stack-name>

Note: User will not be asked for a confirmation before deletion.

List all ClusterStacks

Users can view the list of all ClusterStacks created:

The following is an example of the output for this command:

NAME       READY    ID
base       True     io.buildpacks.stacks.bionic
default    True     io.buildpacks.stacks.bionic
full       True     org.cloudfoundry.stacks.cflinuxfs3
tiny       True     io.paketo.stacks.tiny

How to update an Image for Stack updates only?

To achieve Stack only updates for an Image, you can pin the Buildpack versions in the Builder used for creating the Image.