Managing Images and Builds

Page last updated:

This topic contains the following sections:

The kp CLI can be used to manage images and builds. The help text is published here.

$ kp image
Image commands

Usage:
  kp image [command]

Aliases:
  image, images, imgs, img

Available Commands:
  create      Create an image configuration
  delete      Delete an image
  list        List images
  patch       Patch an existing image configuration
  save        Create or patch an image configuration
  status      Display status of an image
  trigger     Trigger an image 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
  logs        Tails logs for an image build
  status      Display status for an image build

Flags:
  -h, --help   help for build

Use "kp build [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.

Images

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

Build Service will monitor the inputs to the image configuration to rebuild the image when the underlying source or buildpacks have changed.

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

Creating Images

Prerequisites:

Source Code

The kp CLI supports creating Images 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) to be used to create image 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 will be used.

For more information on Builders, see Managing Builders.

Creating an Image With Source Code in a Git Repository

To create an image 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: The name of the image.
  • tag: The registry location where the image will be created.
  • builder: (optional) Builder name to be used in the image. Cannot be used with cluster-builder.
  • cluster-builder: (optional) Cluster Builder name to be used in the image. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace: (optional) The Kubernetes namespace for the image. Defaults to the local Kubernetes current-context namespace.
  • env (optional): Image environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • sub-path (optional): Build code at the sub path located within the source code directory.
  • cache-size (optional): 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 Git repository URL of the source code.
  • git-revision (optional) 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 against a branch, Build Service triggers a build for every new commit. Defaults to master.

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

Create an Image 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 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: The name of the image.
  • tag: The registry location where the image will be created.
  • builder: (optional) Builder name to be used in the image. Cannot be used with cluster-builder.
  • cluster-builder: (optional) Cluster Builder name to be used in the image. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace: (optional) The Kubernetes namespace for the image. Defaults to the local Kubernetes current-context namespace.
  • env (optional): Image environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • sub-path (optional): Build code at the sub path located within the source code directory.
  • cache-size (optional): 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 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 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 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: The name of the image.
  • tag: The registry location where the image will be created.
  • source-path Path to local source code.
  • builder: (optional) Builder name to be used in the image. Cannot be used with cluster-builder.
  • cluster-builder: (optional) Cluster Builder name to be used in the image. Defaults to default when builder is not set. Cannot be used with builder.
  • namespace: (optional) The Kubernetes namespace for the image. Defaults to the local Kubernetes current-context namespace.
  • env (optional): Image environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • cache-size (optional): 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) Add CA certificate for registry API
  • registry-verify-certs (optional) Set whether to verify server’s certificate chain and host name (default true)

Buildpack Configuration

Images 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 Images.

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 Images

Buildpack configuration – including manually selecting buildpacks to use – can be set in two ways in Tanzu Build Service Images. 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.

Tanzu Build Service Images can have environment variables configured which will be 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 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 Images

Users can patch their existing images with the kp CLI. Running a patch will trigger a new build of the image if any of the build inputs are changed.

Note:For handling source code changes in the Tanzu Build Service process, we recommend utilizing the `kp image save –wait` command within a CI/CD pipeline to update the source code referenced in the image configuration.

This can be accomplished by updating the --git-revision field with a new commit ID. For many TBS customers this commit ID references source code that has undergone unit testing, so that they can be confident that the resulting image can be deployed or promoted to higher level environments.

Patch images 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: The name of the image to patch.
  • namespace: (optional) The Kubernetes namespace for the image. Defaults to the local Kubernetes current-context namespace.
  • env (optional): Image environment variable configuration as key=val pairs (env_var=env_val). The --env flag can be specified multiple times.
  • cache-size (optional): The cache size used for subsequent builds. Must be a valid kubernetes quantity (default 2G).
  • git-repo Git repository URL of the source code. Must select one of git-repo, blob-url, or source-path
  • git-revision (optional) 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 against a branch, Build Service triggers a build for every new commit. Defaults to master.
  • blob-url URL of the source code blob file. Must select one of git-repo, blob-url, or source-path
  • source-path 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 cannot be modified. To change these fields, you must create a new image.

Saving Images

Users can create or patch an Image using the save command. The kp image save command is used exactly the same as kp image create or kp image patch, but it will determine if a image needs to be created or patched.

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 configurations in a Kubernetes namespace:

kp image list --namespace <namespace>

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 configurations across all Kubernetes namespaces:

kp image list --all-namespaces

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 Images

Users can further filter the list of Images by applying the --filter flag and specifying a filter and value. This command is useful for traversing large number of Image configurations by narrowing the list to only display Images 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 current supported filters and values:

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

Image Rebuilds

Rebuilds happen in three ways:

  1. An imperative rebuild occurs when you patch an image 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 will be initiated if any of the following changes are made to an image:

  • 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 Images.

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

  • New buildpack versions are made available via 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 (ie. base OS image) available, such as full, tiny, or base.

Trigger an Image Rebuild

You can initiate a manual rebuild using kp:

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

This is useful for debugging image builds.

Viewing the Status of an Image

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

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

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

Where image-name is the name of the image. See Listing Images 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

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

Warning: Deleting an image 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:

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

Where image is the name of the image.

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

"<image>" deleted

Managing Images with YAML

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

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

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 Status

Using kubectl is a good way to debug Images.

When an image has successfully built with its current configuration, its status will report 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 status will report the condition Succeeded=False. The Image status also includes the status of the builder being used by the image. 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’s latest Build status discussed in Viewing Build Details for an Image.

Image Service Bindings

Tanzu Build Service supports application service bindings as described in the Cloud Native Buildpack Service Bindings specification.

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

Creating an Image with Service Bindings

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

  • A Kubernetes Secret containing the service binding data
    • The Secret stringData field must contain key-value pairs of <binding file name>:<binding data>. For each key-value pair, a file will be created that is accessible during build.
  • A Kubernetes ConfigMap containing the metadata for the service binding
    • The ConfigMap must have the fields data.kind and data.provider populated. The buildpacks used to build the image will handle the service bindings based on these fields.
  • A Tanzu Build Service Image referencing that Secret and ConfigMap in the spec.build.bindings field.

Note: Check the desired buildpack documentation for details on the service bindings it supports. To find buildpack docs, see [Store Status](managing-stores.html#show-buildpackages-in-store).

The following is an example that can be used with kubectl apply. It creates a settings.xml service binding for a maven app.

Example:

apiVersion: kpack.io/v1alpha1
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:
    bindings:
    - name: settings
      secretRef:
        name: settings-xml
      metadataRef:
        name: settings-binding-metadata
---
apiVersion: v1
kind: Secret
metadata:
  name: settings-xml
type: Opaque
stringData:
  settings.xml: <settings>...</settings>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: settings-binding-metadata
data:
  kind: maven
  provider: sample

Builds

The procedures in this section describe how to view information and logs for image 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 run:

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

If the namespace is not specified, it defaults to the kubernetes current-context namespace. And if the image-name is not specified, the builds for all the images 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 that they were built.

  • STATUS: Describes the status of a previous build image.

  • IMAGE: 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 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: 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 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: When a build started.

  • Finished: When a build finished.

  • Pod Name: The name of the Pod being used for the Build.

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

  • Run Image: 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: The Git repository URL for Git source, the Blob file URL for Blob source. Unset for Local Source.

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

  • BUILDPACK ID: A list of buildpack ids the build used.

  • BUILDPACK VERSION: A list of buildpack versions the build used.

Image Status shows ImagePullBackOff

If the Build is currently waiting for a container, the Build status will show 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 are seeing this error and you are using a Cluster Builder, you may need to configure a Synced Secret. See When to use Synchronized Secrets.

Getting Build Logs

An image that a user creates will cause 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 will be tailed and will 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 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

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

kp build status <image-name> --bom

For generating the bill of materials, the kp CLI will read metadata from the image (generated by the build) in the registry.

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

As an 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 Notary

Tanzu Build Service supports Notary image signing.

Images signed with Notary require using kubectl instead of kp.

Prerequisites:

  • notary cli
  • A notary server accessible by the Tanzu Build Service cluster

Generate Notary Signing Keys

Only one root signing key is required. Each image that will be signed by notary will require a target and snapshot signing key.

Run the following commands. You will be asked to provide the registry credentials for the <image-repository>:

export NOTARY_ROOT_PASSPHRASE=<notary-root-passphrase>
export NOTARY_SNAPSHOT_PASSPHRASE=<notary-snapshot-passphrase>
notary -s <notary-server-url> init <image-repository>
notary -s <notary-server-url> key rotate <image-repository> snapshot -r
notary -s <notary-server-url> publish <image-repository>

You will be prompted to enter a <notary-targets-passphrase>:

Enter passphrase for targets key with ID <target-hash>:

Where:

  • <notary-root-passphrase> is a secure passphrase (this is the root passphrase and should be secure and stored. This is used to generate and rotate other keys.)
  • <notary-snapshot-passphrase> is a secure passphrase (one per image)
  • <notary-targets-passphrase> is a secure passphrase for the targets (one per image)
  • <notary-server-url> is the notary server url
  • <image-repository> is the repository for the image that will be built by Tanzu Build Service.
  • <target-hash> is the hash for the target signing key.

Note: All passphrases can be entered manually via prompts. Some are set as env vars in the example command for simplicity.

Create a Secret to be used for TBS Image Signing

Run the following:

kubectl create secret generic <notary-secret-name> \
    --from-literal=password=<notary-targets-passphrase> \
    --from-file=~/.notary/private/<target-hash>.key \
    --namespace <image-namespace>

Where:

  • <notary-secret-name> is the arbitrary name of the notary secret
  • <notary-targets-passphrase> is the passphrase used in the previous step
  • <target-hash> is the hash from the previous step
  • <image-namespace> is the namespace where the TBS image will be created

Create an Image that will be Signed by Notary

TBS will sign images when the spec.notary key is populated.

This configuration cannot be set by kp cli, kubectl must be used to create the Image.

Example image.yaml:

apiVersion: kpack.io/v1alpha1
kind: Image
metadata:
  name: my-notary-image
  namespace: <image-namespace>
spec:
  notary:
    v1:
      url: <notary-server-url>
      secretRef:
        name: <notary-secret-name>
  serviceAccount: default
  source:
    git:
      url: github.com/my-git-repo
  tag: <image-repository>
status: {}

Where:

  • <image-namespace> is the namespace used for the secret created in the above step
  • <notary-server-url> is the notary server url used in the first step
  • <notary-secret-name> is the secret name created in the previous step
  • <image-repository> is the image repository used in the first step