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.9.x with Tanzu Build Service v1.9.x. If a feature is not working, you might need to upgrade your CLI.
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.
Prerequisites:
The kp CLI supports creating Image Resources using source code from the following locations:
You can specify only one location for app source code.
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.
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.
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.
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).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.
Common use cases for setting buildpack configuration include:
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, 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.
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"]
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"
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-pathgit-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-pathsource-path is the path to local source code. Must select one of git-repo, blob-url, or source-pathNote: 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.
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
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
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
Rebuilds happen in three ways:
kp image patch.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.
kp CLI. See Updating Build Service Dependencies for more details.You can initiate a manual rebuild using kp:
kp image trigger <image-name> --namespace <namespace>
This is useful for debugging image resource builds.
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
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
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.
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.
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.
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.
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.
Tanzu Build Service supports application service bindings as described in the Kubernetes Service Bindings specification.
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
The procedures in this section describe how to view information and logs for image resource builds using the kp CLI.
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.
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 withbuild-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.
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.
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
Deprecation Note:
The (legacy) CNB BOM format is deprecated, but enabled by default in TBS. Support can be deactivated manually by passing
--data-value-yaml include_legacy_bom=falsetoyttwhen processing the TBS bundle or by addinginclude_legacy_bom=falseto yourtbs-values.ymlfile.The ability to view bill of materials is no longer supported in kp cli 0.9.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"
}
]
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.
Tanzu Build Service supports cosign image signing.
Images signed with cosign require using kubectl instead of kp.
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.
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"
}
}
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.
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.
