This topic tells you how to create and manage image resources of your Tanzu Build Service (commonly known as TBS).

Create Image Resources

Image resources provide a configuration for Tanzu Build Service to build and maintain a Docker image using 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.

Prerequisites:

  • Access to a cluster running Build Service.
  • Configured write secrets for your Docker registry.
  • kp CLI v0.11.x with Tanzu Build Service v1.12.x. Use the kp CLI to manage image resources and builds. For more information, see kpack-cli documentation.

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

You 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 about Builders, see Managing Builders.

Create 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>] \
  --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.
  • 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 blobstore

Specify source code in a blobstore saved as a compressed file (zip, tar.gz, .tar) or a .jar file.

Create an image resource using source code from blobstore:

kp image create <name> \
  --tag <tag> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --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.
  • blob-url is the URL of the source code blob file.
Note

The source code file in the blobstore must be publicly viewable or the ’blob-url` must contain the basic authentication credentials.

Create an image resource with local source code

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

Create an image resource using source code from a local machine:

kp image create <name> \
  --tag <tag> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --local-path <source-path> \
  --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.
  • 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).

Additional flags

In addition to the source related flags, kp image create also accepts these optional flags:

kp image create ... \
  --additional-tag <tag> \
  --cache-size <size>
  --env <env> \
  --namespace <namespace> \
  --service-account <service-account name> \
  --service-binding [<secret-name> or <kind>:<apiVersion>:<name>] \
  --sub-path <sub-path> \
  --wait

Where:

  • additional-tag (optional) is an additional registry location where the image is created. You can specify the --additional-tag flag multiple times.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid Kubernetes quantity (default 2G).
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). You can specify the --env flag multiple times.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • service-account (optional) is the name of the service account to use. Defaults to default.
  • service-binding (optional) is to bind a service to the build process. The long form is <kind>:<apiVersion>:<name>, but if only the <name> is given, the kind and apiVersion is defaulted to Secret:v1. You can specify the --service-binding flag multiple times.
  • sub-path (optional) is the build code at the subpath located within the source code directory.
  • --wait (optional) waits for image create to be reconciled and tails resulting build logs.

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 are found in the documentation for that specific buildpack.

Use kp clusterstore status <store-name> --verbose to find the home page 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. For more information about buildpack details, see Buildpack Configuration Documentation.

  1. Create 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. Set 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"

Patch image resources

You can patch your existing image resources with the kp CLI. Run 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> \
  --git <git-repo> \
  --git-revision <git-revision>

  • With source code in a blobstore

    kp image patch <name> \
  --blob <blob-url>

  • With local source code

    kp image patch <name> \
  --local-path <source-path>

Where:

  • name is the name of the image resource to patch.
  • 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.

Additional flags

In addition to the source related flags, kp image patch also accepts these optional flags:

kp image patch ... \
  --additional-tag <tag> \
  --delete-additional-tag <tag> \
  --replace-additional-tag <tag> \
  [--builder <builder> or --cluster-builder <cluster-builder>] \
  --cache-size <size> \
  --env <env> \
  --delete-env <env> \
  --namespace <namespace> \
  --service-account <service-account name> \
  --service-binding [<secret-name> or <kind>:<apiVersion>:<name>] \
  --delete-service-binding [<secret-name> or <kind>:<apiVersion>:<name>] \
  --sub-path <sub-path> \
  --wait

Where:

  • additional-tag (optional) is an additional registry location where the image is created. You can specify the --additional-tag flag multiple times.
  • delete-additional-tag (optional) removes a registry location that was previously added with --additional-tag. You can specify the --delete-additional-tag flag multiple times.
  • replace-additional-tag (optional) is equivalent to deleting all the previous --additional-tags, and then adding new ones. You can specify the --replace-additional-tag flag multiple times.
  • 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.
  • cache-size (optional) is the cache size used for subsequent builds. Must be a valid Kubernetes quantity (default 2G).
  • env (optional) is the image resource environment variable configuration as key=val pairs (env_var=env_val). You can specify the --env flag multiple times.
  • delete-env (optional) removes an image resource environment variable configuration previously added with --env. You can specify the --delete-env flag multiple times.
  • namespace (optional) is the Kubernetes namespace for the image resource. Defaults to the local Kubernetes current-context namespace.
  • service-account (optional) is the name of the service account to use. Defaults to default.
  • service-binding (optional) is to bind a service to the build process. The long form is <kind>:<apiVersion>:<name>, but if only the <name> is given, the kind and apiVersion is defaulted to Secret:v1. You can specify the --service-binding flag multiple times.
  • delete-service-binding (optional) removes a service binding previously added with --service-binding. You can specify the --delete-service-binding flag multiple times.
  • sub-path (optional) is the build code at the subpath located within the source code directory.
  • --wait (optional) waits for image create to be reconciled and tails resulting build logs.
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.

Save image resources

You can create or patch an image resource using the save command. The kp image save command is used 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 using 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

List 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

Filter the list of image resources by applying the --filter flag and specifying a filter and value. This command is useful for traversing a 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. You 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

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 you create an image resource using the above workflow, you 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.

Note

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

Image resource additional tags

Use the following example with kubectl apply. It pushes to both my-registry.com/repo and my-registry.com/other-repo.

Example:

apiVersion: kpack.io/v1alpha2
kind: Image
metadata:
  name: image-with-multiple-tags
spec:
  tag: my-registry.com/repo
  additionalTags:
  - my-registry.com/other-repo
  builder:
    kind: ClusterBuilder
    name: default
  source:
    git:
      url: https://github.com/buildpack/sample-java-app.git
      revision: 0eccc6c2f01d9f055087ebbf03526ed0623e014a

You can also use the --additional-tag flag in the kp CLI for kp image create, kp image patch, and kp image save.

Managing image resources with YAML

Create Build Services image resources by applying the kpack image resources to cluster through kubectl.

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

Using a registry for caching

You can configure Tanzu Build Service image resource 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 information about how to set the cache tag, see the kpack image config documentation.

Using secrets

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

Debugging with image resource status

Use kubectl 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 can inspect that builder. For more information, see 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 more debugging is required, inspect the image resource’s latest Build status as described in Viewing Build Details for an Image.

Image resource service bindings

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

Creating an image resource with service bindings

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

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

Note

Check the desired buildpack documentation for details about the service bindings it supports. For more information, see Language Family Buildpacks for VMware Tanzu.

Use the following example with kubectl apply. It creates a production-db-secret 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

You can also use the --service-binding flag in the kp CLI for kp image create, kp image patch, and kp image save.

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 and 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 the 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 can 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 you create 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 Notices:

  • The legacy Cloud Native Buildpack Bill of Materials (CNB BOM) format is deprecated and is now deactivated by default in Tanzu Build Service. If required, you can activate it manually by passing --data-value-yaml include_legacy_bom=true to ytt when processing the Tanzu Build Service bundle or by adding include_legacy_bom=true to your tbs-values.yml file. The feature will be removed in Tanzu Build Service v1.13.

  • The ability to view bill of materials is no longer supported in kp CLI v0.9.0 and later.

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.jammy",
        "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 executes as an offline build. For details about how to configure buildpacks, see Buildpack configuration in images.

Note

Offline builds only ensure that 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 is 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 is added to the cosign signing annotations. You can specify additional cosign annotations under the spec key.

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

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

% 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, 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