This topic contains the following sections:

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

$ kp image
Image commands

Usage:
  kp image [command]

Aliases:
  image-resource, images, imgs, img

Available Commands:
  create      Create an image resource
  delete      Delete an image resource
  list        List image resources
  patch       Patch an existing image resource
  save        Create or patch an image resource
  status      Display status for an image resource
  trigger     Trigger an image resource build

Flags:
  -h, --help   help for image

Use "kp image [command] --help" for more information about a command.
$ kp build
Build Commands

Usage:
  kp build [command]

Aliases:
  build, builds, blds, bld

Available Commands:
  list        List builds for an image resource
  logs        Tails logs for an image resource build
  status      Display status for an image resource build

Flags:
  -h, --help   help for build

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

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

Image Resources

Image resources provide a configuration for Tanzu Build Service to build and maintain a Docker image utilizing Tanzu, Paketo, and custom Cloud Native Buildpacks.

Build Service monitors the inputs to the image resource to rebuild the image when the underlying source or buildpacks have changed.

The following procedures describe how to create and manage image resources in Build Service with the kp CLI.

Creating Image Resources

Prerequisites:

Source Code

The kp CLI supports creating Image Resources using source code from the following locations:

You can specify only one location for app source code.

Builders

Users can select a Builder (namespaced-scoped) or a Cluster Builder (cluster-scoped) used to create image resource builds. You can use any of the available Builders or Cluster Builders with any of the source types (git, blob, or local).

If you do not use the --builder or --cluster-builder flags, the default Cluster Builder is used.

For more information on Builders, see Managing Builders.

Creating an image resource with source code in a Git repository

To create an image resource using source code from a git repository, run:

kp image create <name> \
  --tag <tag> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --namespace <namespace> \
  --env <env> \
  --sub-path <sub-path> \
  --wait \
  --git <git-repo> \
  --git-revision <git-revision>

Where:

  • name is the name of the image resource.
  • tag is the registry location where the image is created.
  • builder (optional) is the builder name used in the image resource. Cannot be used with cluster-builder.
  • cluster-builder (optional) is the Cluster Builder name to be used in the image resource. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • sub-path (optional) is the build code at the subpath located within the source code directory.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid kubernetes quantity (default 2G).
  • wait flag (optional) waits for image create to be reconciled and tails resulting build logs.
  • git-repo is the Git repository URL of the source code.
  • git-revision (optional) is the Git revision of the code that the image is built against. Can be either a branch, tag or a commit sha. When you target the image resource against a branch, Build Service triggers a build for every new commit. Defaults to main.

Note: If the git-repo is a private repository, you must configure the Git credentials. For more information, see Create Secrets.

Create an image resource with source code in a blob store

Users can specify source code in a blob store saved as a compressed file (zip, tar.gz, .tar) or a .jar file.

To create an image resource using source code from blob store:

kp image create <name> \
  --tag <tag> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --namespace <namespace> \
  --env <env> \
  --sub-path <sub-path> \
  --wait \
  --blob <blob-url>

Where:

  • name is the name of the image resource.
  • tag is the registry location where the image is created.
  • builder (optional) is the builder name used in the image resource. Cannot be used with cluster-builder.
  • cluster-builder (optional) is the Cluster Builder name to be used in the image resource. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • sub-path (optional) is the build code at the subpath located within the source code directory.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid kubernetes quantity (default 2G).
  • wait flag (optional) waits for image create to be reconciled and tails resulting build logs.
  • blob-url is the URL of the source code blob file.

Note: The source code file in the blob store must be publicly viewable or the blob-url must contain the basic authentication credentials.

Creating an image resource with local source code

Users can apply local source code from a directory, compressed source code (zip, tar.gz, .tar), or a .jar file.

To create an image resource using source code from a local machine, run:

kp image create <name> \
  --tag <tag> \
  --local-path <source-path> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --namespace <namespace> \
  --env <env> \
  --cache \
  --registry-ca-cert-path <path-to-ca-cert> \
  --registry-verify-certs

Where:

  • name is the name of the image resource.
  • tag is the registry location where the image is created.
  • source-path is the path to local source code.
  • builder (optional) is the builder name used in the image resource. Cannot be used with cluster-builder.
  • cluster-builder (optional) is the Cluster Builder name used in the image resource. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid kubernetes quantity (default 2G).
  • --wait flag (optional) waits for image create to be reconciled and tails resulting build logs.
  • registry-ca-cert-path (optional) adds CA certificate for registry API.
  • registry-verify-certs (optional) sets whether to verify server's certificate chain and host name (default true).

Buildpack configuration

Image resources use buildpacks to build application images in a registry. The buildpacks contain the dependencies needed for these builds and you can add buildpack configuration to Tanzu Build Service image resources.

Buildpack configuration use cases

Common use cases for setting buildpack configuration include:

  • Selecting a specific version or version line of a dependency (Go 1.15.*, Java 1.8)
  • Language-specific configuration (Go build target)
  • Buildpack-specific configuration

Buildpack configuration documentation

Buildpack configuration details can be found in the documentation for that specific buildpack.

Use kp clusterstore status <store-name> --verbose to find the homepage of the desired buildpack.

Buildpack configuration in image resources

Buildpack configuration, including manually selecting buildpacks to use, can be set in two ways in Tanzu Build Service Image Resources. The configuration depends on the specific buildpack, find buildpack details in Buildpack Configuration Documentation.

  1. Creating a buildpack.yml file at the root of the application source code.

Example buildpack.yml for a Go app to use the latest Go 1.15 version and build with the path ./cmd/package:

go:
  version: 1.15.*
  targets: ["./cmd/package"]
  1. Setting environment variables on an image resource.

Tanzu Build Service image resources can have environment variables configured that are set in all Builds and in the final exported registry image. These can be used for buildpack configuration.

Example kp command to create an image resource for a Go app to build with the path ./cmd/package:

kp image create my-image \
  --tag registry.io/my-repo \
  --git https://github.com/my-go-app \
  --env BP_GO_TARGETS="./cmd/package"

Patching image resources

Users can patch their existing image resources with the kp CLI. Running a patch triggers a new build of the image resource if any of the build inputs are changed.

Patch image resources with the following commands:

  • With source code in a Git repository

    kp image patch <name> \
        [--builder <builder> or --cluster-builder <cluster-builder>] \
        --namespace <namespace> \
        --env <env> \
        --wait \
        --git <git-repo> \
        --git-revision <git-revision>
    
  • With source code in a blob store

    kp image patch <name> \
        [--builder <builder> or --cluster-builder <cluster-builder>] \
        --namespace <namespace> \
        --env <env> \
        --wait \
        --blob <blob-url>
    
  • With local source code

    kp image patch <name> \
        [--builder <builder> or --cluster-builder <cluster-builder>] \
        --namespace <namespace> \
        --env <env> \
        --wait \
        --local-path <source-path>
    

Where:

  • name is the name of the image resource to patch.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid Kubernetes quantity (default 2G).
  • git-repo is the Git repository URL of the source code. Must select one of git-repo, blob-url, or source-path
  • git-revision (optional) is the Git revision of the code that the image is built against. Can be either a branch, tag or a commit sha. When you target the image resource against a branch, Build Service triggers a build for every new commit. Defaults to main.
  • blob-url is the URL of the source code blob file. Must select one of git-repo, blob-url, or source-path
  • source-path is the path to local source code. Must select one of git-repo, blob-url, or source-path

Note: If the git-repo is a private repository, you must configure the Git credentials. For more information, see Create Secrets.

Note: The tag location in a registry and name of an image resource cannot be modified. To change these fields, you must create a new image resource.

Saving image resources

Users can create or patch an image resource using the save command. The kp image save command is used exactly the same as kp image create or kp image patch, but it determines whether an image resource needs to be created or patched.

Note:For handling source code changes in the Tanzu Build Service process, VMware recommends utilizing the `kp image save --wait` command within a CI/CD pipeline to update the source code referenced in the image resource.

You can do this by updating the `--git-revision` field with a new commit ID. This commit ID references source code that has undergone unit testing, so the resulting image can be deployed or promoted to higher level environments.
kp image save my-image \
  --tag my-registry.com/my-repo \
  --git https://my-repo.com/my-app.git \
  --git-revision my-branch

Listing images

To list all the image resources in a Kubernetes namespace:

kp image list --namespace <namespace>

For example:

$ kp image list -n example1

NAME            READY     LATEST REASON    LATEST IMAGE         NAMESPACE
test-image1     True      CONFIG           first/image:sha      example1
test-image2     False     BUILDPACK        second/image:sha     example1

To list all the image resources across all Kubernetes namespaces:

kp image list --all-namespaces

For example:

$ kp image list -A

NAME            READY     LATEST REASON    LATEST IMAGE         NAMESPACE
test-image1     True      CONFIG           first/image:sha      example1
test-image2     True      BUILDPACK        second/image:sha     example1
test-image3     True      BUILDPACK        third/image:sha      example2
test-image4     False     CONFIG           fourth/image:sha     example2

Filter image resources

Users can further filter the list of image resources by applying the --filter flag and specifying a filter and value. This command is useful for traversing large number of image resources by narrowing the list to only display image resources that possess certain attributes.

$ kp image list --filter ready=false -A

NAME            READY     LATEST REASON    LATEST IMAGE         NAMESPACE
test-image2     False     BUILDPACK        second/image:sha     example1
test-image4     False     CONFIG           fourth/image:sha     example2

See below for the currently supported filters and values:

builder=string
clusterbuilder=string
latest-reason=commit,trigger,config,stack,buildpack
ready=true,false,unknown

Image resource rebuilds

Rebuilds happen in three ways:

  1. An imperative rebuild occurs when you patch an image resource with kp image patch.
  2. An automatic rebuild occurs when build inputs change (source code, stack, or buildpacks).
  3. A user can trigger a rebuild manually.

An imperative rebuild is initiated if any of the following changes are made to an image resource:

  • An update to the commit, branch, Git repository, or other arguments to kp image patch.

  • You upload a new copy of the local source code by running kp image patch --local-path <source-path>, where <source-path> is the source code path.

For more information, see Patching image resources.

Build Service auto-rebuilds image resources when one or more of the following build inputs change:

  • New buildpack versions are made available through updates to a Cluster Store.

  • There is a new commit on a branch or tag Tanzu Build Service is tracking.

  • There is a new Cluster Stack (that is, base OS image) available, such as full, tiny, or base.

Trigger an image resource rebuild

You can initiate a manual rebuild using kp:

kp image trigger <image-name> --namespace <namespace>

This is useful for debugging image resource builds.

Viewing the status of an image resource

When a user creates an image resource using the above workflow, they are configuring Tanzu Build Service to start creating builds of the image resource that create container images to be pushed to a registry.

If a particular build associated with an image resource fails, check the status of the image resource by running:

kp image status <image-name> --namespace <namespace>

Where image-name is the name of the image resource. See Listing image resources to get image names.

The following is an example output of this command:

Status:          Not Ready
Message:         --
LatestImage:     gcr.io/myapp@sha256:9d7b1fbf7f5cb0f8efe797f30e598b5e38bb1c08ada143d4c96e4f78111a9239

Last Successful Build
Id:        1
Reason:    CONFIG

Last Failed Build
Id:        2
Reason:    COMMIT

Deleting an image resource

This procedure describes how to delete a Build Service image resource with the kp CLI.

Warning: Deleting an image resource deletes the image resource and all the builds that the image resource owns. It does not delete the app images generated by those builds from the registry.

To delete an image resource:

kp image delete <image> --namespace <namespace>

Where image is the name of the image resource.

When you successfully delete an image resource, you see this message:

"<image>" deleted

Managing image resources with YAML

Build Services image resources can be created by applying the kpack image resources to cluster through kubectl.

Use the default service account for Build Service registry and Git secrets.

Image resource additional tags

With the addition of kpack apiVersion kpack.io/v1alpha2, additional tags can be specified on image resources. Additional tags are not currently configurable through the kp cli, applying YAML configuration with kubectl is required. See kpack docs for details.

Using a registry for caching

Tanzu Build Service image resource can be configured to use a registry as the build cache instead of a persistent volume. Currently, configuring the registry cache is not supported with kp and kubectl must be used.

For more details, see the kpack image config docs for how to set the cache tag.

Using secrets

Use the default service account for Build Service registry and Git secrets. kpack will default to the default service account if no service account is specified.

Debugging with image resource status

Using kubectl is a good way to debug image resources.

When an image resource has successfully built with its current configuration, its status reports the up-to-date fully qualified built image reference.

This information is available with kubectl get image <image-name> -o yaml.

status:
  conditions:
  - lastTransitionTime: "2020-01-17T16:16:36Z"
    status: "True"
    type: Succeeded
  - lastTransitionTime: "2020-01-17T16:16:36Z"
    status: "True"
    type: BuilderReady
  latestImage: index.docker.io/sample/image@sha256:d3eb15a6fd25cb79039594294419de2328f14b443fa0546fa9e16f5214d61686
  ...

When a build fails, the image resource status reports the condition Succeeded=False. The image resource status also includes the status of the builder used by the image resource. If the builder is not ready, you may want to inspect that builder. More details in Managing Builders.

status:
  conditions:
  - lastTransitionTime: "2020-01-17T16:13:48Z"
    status: "False"
    type: Succeeded
    message: "Some error occurred"
  - lastTransitionTime: "2020-01-17T16:16:36Z"
  	status: "False"
  	type: BuilderReady
  	message: "Some builder error occurred"
  ...

If further debugging is required, inspect the image resource's latest Build status discussed in Viewing Build Details for an Image Resource.

Image resource service bindings

Tanzu Build Service supports application service bindings as described in the Kubernetes Service Bindings specification.

The kp CLI does not currently support creating service bindings, you should use kubectl.

Creating an image resource with service bindings

For more information, see Service Bindings in the kpack documentation on GitHub.

To create a service binding in your application image, you must create either of the following:

Note: Check the desired buildpack documentation for details on the service bindings it supports. You can access these docs on [Language Family Buildpacks for VMware Tanzu](https://docs.vmware.com/en/VMware-Tanzu-Buildpacks/services/tanzu-buildpacks/GUID-index.html).

The following is an example you can use with kubectl apply. It creates a production-db service binding for a maven app.

Example:

apiVersion: kpack.io/v1alpha2
kind: Image
metadata:
  name: sample-binding-with-secret
spec:
  tag: my-registry.com/repo
  builder:
    kind: ClusterBuilder
    name: default
  source:
    git:
      url: https://github.com/buildpack/sample-java-app.git
      revision: 0eccc6c2f01d9f055087ebbf03526ed0623e014a
  build:
    services:
    - name: production-db-secret
      kind: Secret
---
apiVersion: v1
kind: Secret
metadata:
  name: production-db-secret
type: servicebinding.io/mysql
stringData:
  type: mysql
  provider: bitnami
  host: localhost
  port: 3306
  username: root
  password: root

Builds

The procedures in this section describe how to view information and logs for image resource builds using the kp CLI.

Listing builds

Build Service stores the ten most recent successful builds and the ten most recent failed builds.

To see a the list of builds for an image resource, run:

kp build list <image-name> --namespace <namespace>

If the namespace is not specified, it defaults to the Kubernetes current-context namespace. If the image-name is not specified, the builds for all the image resources in your namespace are listed.

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

BUILD    STATUS    IMAGE                           REASON
1        SUCCESS   gcr.io/myapp@sha256:some-sha1   CONFIG
2        SUCCESS   gcr.io/myapp@sha256:some-sha2   COMMIT
3        SUCCESS   gcr.io/myapp@sha256:some-sha3   STACK
4        FAILURE   gcr.io/myapp@sha256:some-sha4   CONFIG+
5        BUILDING  gcr.io/myapp@sha256:some-sha5   BUILDPACK

The following describes the fields in the example output:

  • BUILD describes the index of builds in the order they were built.

  • STATUS describes the status of a previous build image.

  • IMAGE is the full image reference for the app image produced by the build.

  • REASON describes why an image rebuild occurred. These reasons include:

    • CONFIG: Occurs when a change is made to commit, branch, Git repository, or build fields on the image's configuration file and you run kp image apply.
    • COMMIT: Occurs when new source code is committed to a branch or tag that Build Service is monitoring for changes.
    • BUILDPACK: Occurs when new buildpack versions are made available through an updated builder.
    • STACK: Occurs when a new base OS image, called a run image, is available.
    • TRIGGER: Occurs when a new build is manually triggered.

Note: A rebuild can occur for more than one reason. When there are multiple reasons for a rebuild, the kp CLI output shows the primary Reason and appends a + sign to the Reason field. The priority rank for the Reason, from highest to lowest, is CONFIG, COMMIT, BUILDPACK, STACK, and TRIGGER.

Viewing build details for an image

To display retrieve a detailed bill of materials for a particular build:

kp build status <image> -b <build-number>

Where:

  • image-name is the name of the image resource the build is associated with
  • build-name (optional) is the index of the build from listing builds. Defaults to latest build.

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

Image:      gcr.io/myapp@sha256:f87b614257af05c3301c1554c4f15131793caec3adf55e45d2c612e90445765a
Status:     SUCCESS
Reason:     CONFIG
            resources
	        - source: {}
	        + source:
	        +   git:
	        +     revision: 948b2eff6a21580a44a0f4d8c609a2af45359d41
	        +     url: https://github.com/paketo-buildpacks/samples
	        +   subPath: go/mod

Started:    2021-02-02 18:34:33
Finished:   2021-02-02 18:41:03

Pod Name:   build-pod-xyz

Builder:    gcr.io/my-builder:base@sha256:grtewwads0asdvf09asdf
Run Image:  gcr.io/base-image:run@sha256:asdas098asdas

Source:     Git
Url:        http://github.com/myapp
Revision:   ad123ad

BUILDPACK ID        BUILDPACK VERSION
io.java.etc         123
io.kotlin.etc       321

The following describes the fields in the example output:

  • Image is the full image reference for the app image produced by the build.

  • Status describes the status of a previous build image.

  • Reason describes why an image resource build occurred and the change diff. The reason could be one or more of these:

    • CONFIG: Occurs when a change is made to commit, branch, Git repository, or build fields on the image's configuration file and you run kp image apply.
    • COMMIT: Occurs when new source code is committed to a branch or tag that Build Service is monitoring for changes.
    • BUILDPACK: Occurs when new buildpack versions are made available through an updated builder.
    • STACK: Occurs when a new base OS image (called a run image) is available.
    • TRIGGER: Occurs when a new build is manually triggered.
  • Started is when a build started.

  • Finished is when a build finished.

  • Pod Name is the name of the Pod being used for the Build.

  • Builder is the full image tag for the builder image used by the build.

  • Run Image is the full image tag for the run image used by the app.

  • Source describes where the source code used to build the image is coming from. Can be Git, Blob, or Local Source.

  • Url is the Git repository URL for Git source, the Blob file URL for Blob source. Unset for Local Source.

  • Revision is the Git commit sha of the source code used to create the build for Git source.

  • BUILDPACK ID is a list of buildpack ids the build used.

  • BUILDPACK VERSION is a list of buildpack versions the build used.

Image resource status shows ImagePullBackOff

If the Build is currently waiting for a container, the Build status shows details in the output of kp build status.

Here is an example output:

Image:            --
Status:           BUILDING
Reason:           CONFIG
Status Reason:    ImagePullBackOff
Status Message:   A container image currently cannot be pulled: Back-off pulling image "gcr.io/my-builder:base@sha256:grtewwads0asdvf09asdf"

Pod Name:    build-pod-xyz

Builder:    gcr.io/my-builder:base@sha256:grtewwads0asdvf09asdf
Run Image:  gcr.io/base-image:run@sha256:asdas098asdas

Source:      Git
Url:         http://github.com/myapp
Revision:    ad123ad

BUILDPACK ID        BUILDPACK VERSION

If you see this error and you are using a Cluster Builder, you might need to configure a Synced Secret. See When to use Synchronized Secrets.

Getting build logs

An image resource that a user creates causes builds to be initiated for that image. Builds are where Cloud Native Buildpacks are run and apps get built into images.

Build logs are a good way to debug issues and to get information about how your app is being built.

If you get logs of a build in progress, the logs are tailed and terminate when the build completes.

To get logs from a build run:

kp build logs <image> --build <build-number> --namespace <namespace>

Where:

  • image-name is the name of the image resource the build is associated with.
  • build-name (optional) is the index of the build from listing builds. Defaults to latest build.

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

===> PREPARE
Build reason(s): CONFIG
CONFIG:
	resources: {}
	- source: {}
	+ source:
	+   git:
	+     revision: 446dbda043ca103d33e2cad389d43f289e63f647
	+     url: https://github.com/some-org/some-repo
Loading secret for "gcr.io" from secret "gcr" at location "/var/build-secrets/gcr"
Cloning "https://github.com/some-org/some-repo" @ "446dbda043ca103d33e2cad389d43f289e63f647"...
Successfully cloned "https://github.com/some-org/some-repo" @ "446dbda043ca103d33e2cad389d43f289e63f647" in path "/workspace"
===> DETECT
tanzu-buildpacks/node-engine 0.1.2
tanzu-buildpacks/npm-install 0.1.1
tanzu-buildpacks/npm-start   0.0.2
===> ANALYZE
Previous image with name "gcr.io/test-app" not found
===> RESTORE
===> BUILD
Tanzu Node Engine Buildpack 0.1.2
  Resolving Node Engine version
    Candidate version sources (in priority order):
                -> ""
      <unknown> -> "*"

    Selected Node Engine version (using ): 14.15.1

  Executing build process
    Installing Node Engine 14.15.1
      Completed in 2.495s

  Configuring environment
    NODE_ENV     -> "production"
    NODE_HOME    -> "/layers/tanzu-buildpacks_node-engine/node"
    NODE_VERBOSE -> "false"

    Writing profile.d/0_memory_available.sh
      Calculates available memory based on container limits at launch time.
      Made available in the MEMORY_AVAILABLE environment variable.

Tanzu NPM Install Buildpack 0.1.1
  Resolving installation process
    Process inputs:
      node_modules      -> "Not found"
      npm-cache         -> "Not found"
      package-lock.json -> "Not found"

    Selected NPM build process: 'npm install'

  Executing build process
    Running 'npm install --unsafe-perm --cache /layers/tanzu-buildpacks_npm-install/npm-cache'
      Completed in 3.591s

  Configuring environment
    NPM_CONFIG_LOGLEVEL   -> "error"
    NPM_CONFIG_PRODUCTION -> "true"
    PATH                  -> "$PATH:/layers/tanzu-buildpacks_npm-install/modules/node_modules/.bin"

Tanzu NPM Start Buildpack 0.0.2
  Assigning launch processes
    web: node server.js
===> EXPORT
Adding layer 'tanzu-buildpacks/node-engine:node'
Adding layer 'tanzu-buildpacks/npm-install:modules'
Adding layer 'tanzu-buildpacks/npm-install:npm-cache'
Adding 1/1 app layer(s)
Adding layer 'launcher'
Adding layer 'config'
Adding label 'io.buildpacks.lifecycle.metadata'
Adding label 'io.buildpacks.build.metadata'
Adding label 'io.buildpacks.project.metadata'
*** Images (sha256:0abdbaf1f25c3c13cdb918d06906670b84dd531bc7301177b11284dac68bdb9c):
      gcr.io/test-app
      gcr.io/test-app:b1.20210203.225422
Adding cache layer 'tanzu-buildpacks/node-engine:node'
Adding cache layer 'tanzu-buildpacks/npm-install:modules'
Adding cache layer 'tanzu-buildpacks/npm-install:npm-cache'
===> COMPLETION
Build successful

Viewing bill of materials

Deprecation Note:

  • The (legacy) CNB BOM format is deprecated, but enabled by default in TBS. Support can be disabled manually by passing --data-value-yaml include_legacy_bom=false to ytt when processing the TBS bundle or by adding include_legacy_bom=false to your tbs-values.yml file.

  • The ability to view bill of materials is no longer supported in kp cli 0.7.0+.

The kp cli allows you to view the bill of materials in an image built by a Build.

kp build status <image-name> --bom

To generate the bill of materials, the kp CLI reads metadata from the image (generated by the build) in the registry.

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

For example:

$ kp build status --bom my-app-image | jq
[
  {
    "buildpack": {
      "id": "tanzu-buildpacks/node-engine",
      "version": "0.1.2"
    },
    "metadata": {
      "licenses": [],
      "name": "Node Engine",
      "sha256": "b981046a0ea3d5594a7f04fae3afdfa1983bc65f4e26e768b38a2d67057ac75c",
      "stacks": [
        "io.buildpacks.stacks.bionic",
        "org.cloudfoundry.stacks.cflinuxfs3"
      ],
      "uri": "file:///dependencies/b981046a0ea3d5594a7f04fae3afdfa1983bc65f4e26e768b38a2d67057ac75c",
      "version": "14.15.1"
    },
    "name": "node",
    "version": "14.15.1"
  },
  {
    "buildpack": {
      "id": "tanzu-buildpacks/npm-install",
      "version": "0.1.1"
    },
    "metadata": {
      "launch": true
    },
    "name": "node_modules"
  }
]

Offline builds

Tanzu Build Service supports offline/air-gapped builds with Tanzu Buildpacks. Offline builds use pre-packaged dependencies and do not need to download from anywhere off-cluster to create application images.

When using Tanzu Buildpacks the build will execute as an offline build. For details on how to configure buildpacks, see Buildpack configuration in images.

Note: Offline builds only ensure buildpack dependencies are offline. The application build and custom configuration must also not reach off-cluster to be completely offline.

Image signing with cosign

Tanzu Build Service supports cosign image signing.

Images signed with cosign require using kubectl instead of kp.

Cosign signing secret

Images can be signed with cosign when a cosign formatted secret is added to the service account used to build the image. The secret can be added using the cosign CLI or manually.

To create a cosign signing secret through the cosign CLI, when targetted to the Kubernetes cluster, use:

cosign generate-key-pair k8s://[NAMESPACE]/[NAME]

Alternatively, create the cosign secret and provide your own cosign key files manually to Kubernetes by running the following command:

% kubectl create secret generic <secret-name> --from-literal=cosign.password=<password> --from-file=</path/to/cosign.key>
  • <secret-name> is the name of the secret. Ensure that the secret is created in the same namespace as the eventual image resource.
  • <password> is the password provided to encrypt the private key. If not present, an empty password will be used.
  • </path/to/cosign.key> is the cosign private key file generated with cosign generate-key-pair.

After adding the cosign secret, the secret must be added to the list of secrets attached to the service account resource that is building the image.

Adding cosign annotations

By default, the build number and build timestamp information ise added to the cosign signing annotations. Users can specify additional cosign annotations under the spec key.

cosign:
  annotations:
  - name: "annotationName"
    value: "annotationValue"

One way these annotations can be viewed is through verifying cosign signatures. The annotations are under the optional key in the verified JSON response. For example, you can do this by running:

% cosign verify -key /path/to/cosign.pub registry.example.com/project/image@sha256:<DIGEST>

Which provides a JSON response similar to:

{
  "critical": {
    "identity": {
      "docker-reference": "registry.example.com/project/image"
    }, "image": {
      "docker-manifest-digest": "sha256:<DIGEST>"
    }, "type": "cosign container image signature"
  }, "optional": {
    "buildNumber": "1",
    "buildTimestamp": "20210827.175240",
    "annotationName": "annotationValue"
  }
}

Push cosign signature to a different location

Cosign signatures can be pushed to a different registry from where the image is located. To enable this, add the corresponding annotation to the cosign secret resource:

metadata:
  name: ...
  namespace: ...
  annotations:
    kpack.io/cosign.repository: other.registry.com/project/image
data:
  cosign.key: ...
  cosign.password: ...

This is equivalent to setting COSIGN_REPOSITORY as specified in cosign Specifying Registry on GitHub.

The same service account that has that cosign secret attached, and is used for signing and building the image, requires that the registry credentials for this other repository be placed under the listed secrets. It is not required to be listed in imagePullSecrets. To push the signatures to the same registry but to a different path from the image, the credential used must have access to both paths. You cannot use two separate credentials for the same registry with different paths.

Cosign legacy Docker media types

To sign images in a registry that does not fully support OCI media types, you can use legacy equivalents by adding the corresponding annotation to the cosign secret resource:

metadata:
  name: ...
  namespace: ...
  annotations:
    kpack.io/cosign.docker-media-types: "1"
data:
  cosign.key: ...
  cosign.password: ...

This is equivalent to setting COSIGN_DOCKER_MEDIA_TYPES=1 as specified in the cosign registry-support.

check-circle-line exclamation-circle-line close-line
Scroll to top icon