Managing Images and Builds
Page last updated:
This topic contains the following sections:
Images
Images provide a configuration for 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:
- Access to a cluster running Build Service.
- Configured write secrets for your Docker registry.
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 Custom Builder or a Custom Cluster Builder to be used to create image builds. You can use any of the available Custom Builders or Custom Cluster Builders with any of the source types (git, blob, or local).
If you do not use the --custom-builder
or --custom-cluster-builder
flags, the default
Custom 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> \
[--custom-builder <custom-builder> or --custom-cluster-builder <custom-cluster-builder>] \
--namespace <namespace> \
--env <env> \
--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.custom-builder
: (optional) Custom Builder name to be used in the image. Cannot be used withcustom-cluster-builder
.custom-cluster-builder
: (optional) Custom Cluster Builder name to be used in the image. Defaults todefault
whencustom-builder
is not set. Cannot be used withcustom-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.--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 abranch
,tag
or a commitsha
. When you target the image against a branch, Build Service triggers a build for every new commit. Defaults tomaster
.
Note: If the git-repo
is a private repository, you must configure the git credentials. For more information, see Managing Git Repositories for a Project.
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> \
[--custom-builder <custom-builder> or --custom-cluster-builder <custom-cluster-builder>] \
--namespace <namespace> \
--env <env> \
--wait \
--blob <blob-url>
Where:
name
: The name of the image.tag
: The registry location where the image will be created.custom-builder
: (optional) Custom Builder name to be used in the image. Cannot be used withcustom-cluster-builder
.custom-cluster-builder
: (optional) Custom Cluster Builder name to be used in the image. Defaults todefault
whencustom-builder
is not set. Cannot be used withcustom-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.--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> \
[--custom-builder <custom-builder> or --custom-cluster-builder <custom-cluster-builder>] \
--namespace <namespace> \
--env <env> \
--wait \
--local-path <source-path>
Where:
name
: The name of the image.tag
: The registry location where the image will be created.custom-builder
: (optional) Custom Builder name to be used in the image. Cannot be used withcustom-cluster-builder
.custom-cluster-builder
: (optional) Custom Cluster Builder name to be used in the image. Defaults todefault
whencustom-builder
is not set. Cannot be used withcustom-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.--wait
flag (optional) Waits for image create to be reconciled and tails resulting build logs.source-path
Path to local source code.
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.
Patch images with the following commands:
With Source Code in a Git Repository
kp image patch <name> \ [--custom-builder <custom-builder> or --custom-cluster-builder <custom-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> \ [--custom-builder <custom-builder> or --custom-cluster-builder <custom-cluster-builder>] \ --namespace <namespace> \ --env <env> \ --wait \ --blob <blob-url>
With Local Source Code
kp image patch <name> \ [--custom-builder <custom-builder> or --custom-cluster-builder <custom-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.git-repo
Git repository URL of the source code. Must select one ofgit-repo
,blob-url
, orsource-path
git-revision
(optional) The Git revision of the code that the image is built against. Can be either abranch
,tag
or a commitsha
. When you target the image against a branch, Build Service triggers a build for every new commit. Defaults tomaster
.blob-url
URL of the source code blob file. Must select one ofgit-repo
,blob-url
, orsource-path
source-path
Path to local source code. Must select one ofgit-repo
,blob-url
, orsource-path
Note: If the git-repo
is a private repository, you must configure the git credentials. For more information, see Managing Git Repositories for a Project.
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.
Listing Images
To list all the image configurations in a Kubernetes namespace:
kp image list --namespace <namespace>
The following is an example of the output for this command:
NAME READY LATEST IMAGE
first-image True first/image:tag
second-image True second/image:tag
first-image False third/image:tag
Image Rebuilds
Rebuilds happen in three ways:
- An imperative rebuild occurs when you patch an image with
kp image patch
. - An automatic rebuild occurs when build inputs change (source code, stack, or buildpacks).
- 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 through an updated builder image.
- The Build Service Bundle on Tanzu Network includes the latest buildpacks contained in a builder image.
- When upgrading TBS, you must relocate new buildpack versions over to your container registry. See Updating Build Service Dependencies for more details.
There is a new commit on a branch or tag Tanzu Build Service is tracking.
There is a new Stack (ie. base OS image) available, such as
full
,tiny
, orbase
.
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
Builds
The procedures in this section describe how to view information and logs for image builds using the kp
CLI.
Listing Builds for an Image
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>
The following is an example of the output for this command:
BUILD STATUS IMAGE STARTED FINISHED REASON
1 SUCCESS gcr.io/myapp@sha256:some-sha1 2019-09-09 21:55:27 2019-07-08 21:55:54 CONFIG
2 SUCCESS gcr.io/myapp@sha256:some-sha2 2019-09-09 21:56:55 2019-07-08 21:57:40 COMMIT
3 SUCCESS gcr.io/myapp@sha256:some-sha3 2019-09-09 21:57:55 2019-07-08 21:58:40 STACK
4 FAILURE gcr.io/myapp@sha256:some-sha4 2019-09-09 21:58:55 2019-07-08 21:59:40 CONFIG+
5 BUILDING gcr.io/myapp@sha256:some-sha5 2019-09-09 21:59:55 -- BUILDER
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.STARTED
: Describes when a build started.FINISHED
: Describes when a build finished.REASON
: Describes why an image rebuild occured. 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 runkp image apply
.COMMIT
: Occurs when new source code is committed to a branch or tag that Build Service is monitoring for changes.BUILDER
: Occurs when new buildpack versions are made available through an updated builder image.Note: A rebuild can occur for more than one reason. When there are multiple reasons for a rebuild, the
kp
CLI output shows the primaryReason
and appends a+
sign to theReason
field. The priority rank for theReason
, from highest to lowest, isCONFIG
,COMMIT
, andBUILDER
.STACK
: Occurs when a new base OS image, called arun image
, is available.TRIGGER
: Occurs when a new build is manually triggered.
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 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
Reasons: CONFIG
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 rebuild occured. 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 runkp image apply
.COMMIT
: Occurs when new source code is committed to a branch or tag that Build Service is monitoring for changes.BUILDER
: Occurs when new buildpack versions are made available through an updated builder image.Note: A rebuild can occur for more than one reason. When there are multiple reasons for a rebuild, the
kp
CLI output shows the primaryReason
and appends a+
sign to theReason
field. The priority rank for theReason
, from highest to lowest, isCONFIG
,COMMIT
, andBUILDER
.STACK
: Occurs when a new base OS image (called arun image
) is available.TRIGGER
: Occurs when a new build is manually triggered.
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 beGit
,Blob
, orLocal Source
.Url
: The Git repository URL forGit
source, the Blob file URL forBlob
source. Unset forLocal Source
.Revision
: The Git commit sha of the source code used to create the build forGit
source.BUILDPACK ID
: A list of buildpack ids the build used.BUILDPACK VERSION
: A list of buildpack versions the build used.
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 withbuild-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
Loading secret for "gcr.io" from secret "some-creds" at location "/var/build-secrets/some-creds"
Successfully pulled gcr.io/test-app-source@sha256:d6ddb6d02e07b2a40022929ca83d73482ae1aff99edefc10c76f43ff57d3ef40 in path "/workspace"
===> DETECT
6 of 32 buildpacks participating
paketo-buildpacks/bellsoft-liberica 2.7.3
paketo-buildpacks/maven 1.4.3
paketo-buildpacks/executable-jar 1.2.5
paketo-buildpacks/apache-tomcat 1.2.2
paketo-buildpacks/dist-zip 1.3.3
paketo-buildpacks/spring-boot 1.5.5
===> ANALYZE
Previous image with name "gcr.io/test-app" not found
===> RESTORE
===> BUILD
Paketo BellSoft Liberica Buildpack 2.7.3
https://github.com/paketo-buildpacks/bellsoft-liberica
Build Configuration:
$BP_JVM_VERSION 11.* (default) the Java version
Launch Configuration:
$BPL_JVM_HEAD_ROOM 0 (default) the headroom in memory calculation
$BPL_JVM_LOADED_CLASS_COUNT 35% of classes (default) the number of loaded classes in memory calculation
$BPL_JVM_THREAD_COUNT 250 (default) the number of threads in memory calculation
BellSoft Liberica JDK 11.0.7: Contributing to layer
Downloading from https://github.com/bell-sw/Liberica/releases/download/11.0.7+10/bellsoft-jdk11.0.7+10-linux-amd64.tar.gz
Verifying checksum
Expanding to /layers/paketo-buildpacks_bellsoft-liberica/jdk
Adding 134 container CA certificates to JVM truststore
Writing env.build/JAVA_HOME.override
Writing env.build/JDK_HOME.override
BellSoft Liberica JRE 11.0.7: Contributing to layer
Downloading from https://github.com/bell-sw/Liberica/releases/download/11.0.7+10/bellsoft-jre11.0.7+10-linux-amd64.tar.gz
Verifying checksum
Expanding to /layers/paketo-buildpacks_bellsoft-liberica/jre
Writing env.launch/JAVA_HOME.override
Writing env.launch/MALLOC_ARENA_MAX.override
Writing profile.d/active-processor-count.sh
Memory Calculator 4.0.0: Contributing to layer
Downloading from https://github.com/cloudfoundry/java-buildpack-memory-calculator/releases/download/v4.0.0/memory-calculator-4.0.0.tgz
Verifying checksum
Expanding to /layers/paketo-buildpacks_bellsoft-liberica/memory-calculator
Writing profile.d/memory-calculator.sh
Class Counter: Contributing to layer
Copying to /layers/paketo-buildpacks_bellsoft-liberica/class-counter
JVMKill Agent 1.16.0: Contributing to layer
Downloading from https://github.com/cloudfoundry/jvmkill/releases/download/v1.16.0.RELEASE/jvmkill-1.16.0-RELEASE.so
Verifying checksum
Copying to /layers/paketo-buildpacks_bellsoft-liberica/jvmkill
Writing env.launch/JAVA_OPTS.append
Link-Local DNS: Contributing to layer
Copying to /layers/paketo-buildpacks_bellsoft-liberica/link-local-dns
Writing profile.d/link-local-dns.sh
Java Security Properties: Contributing to layer
Writing env.launch/JAVA_OPTS.append
Writing env.launch/JAVA_SECURITY_PROPERTIES.override
Security Providers Configurer: Contributing to layer
Copying to /layers/paketo-buildpacks_bellsoft-liberica/security-providers-configurer
Writing profile.d/security-providers-classpath.sh
Writing profile.d/security-providers-configurer.sh
OpenSSL Certificate Loader: Contributing to layer
Copying to /layers/paketo-buildpacks_bellsoft-liberica/openssl-security-provider
Writing profile.d/openssl-certificate-loader.sh
Paketo Maven Buildpack 1.4.3
https://github.com/paketo-buildpacks/maven
Build Configuration:
$BP_MAVEN_BUILD_ARGUMENTS -Dmaven.test.skip=true package (default) the arguments to pass to Maven
$BP_MAVEN_BUILT_ARTIFACT target/*.[jw]ar (default) the built application artifact explicitly. Supersedes $BP_MAVEN_BUILT_MODULE
$BP_MAVEN_BUILT_MODULE (default) the module to find application artifact in
Creating cache directory /home/vcap/.m2
Compiled Application: Contributing to layer
Executing mvnw -Dmaven.test.skip=true package
[INFO] --- spring-boot-maven-plugin:2.3.0.RELEASE:repackage (repackage) @ spring-petclinic ---
[INFO] Replacing main artifact with repackaged archive
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 03:10 min
[INFO] Finished at: 2020-06-09T21:35:17Z
[INFO] ------------------------------------------------------------------------
Removing source code
Paketo Executable JAR Buildpack 1.2.5
Writing env.launch/CLASSPATH
Process types:
executable-jar: java -cp "${CLASSPATH}" ${JAVA_OPTS} org.springframework.boot.loader.JarLauncher
task: java -cp "${CLASSPATH}" ${JAVA_OPTS} org.springframework.boot.loader.JarLauncher
web: java -cp "${CLASSPATH}" ${JAVA_OPTS} org.springframework.boot.loader.JarLauncher
Paketo Spring Boot Buildpack 1.5.5
Image labels:
org.opencontainers.image.title
org.opencontainers.image.version
org.springframework.boot.spring-configuration-metadata.json
org.springframework.boot.version
===> EXPORT
Adding layer 'launcher'
Adding layer 'paketo-buildpacks/bellsoft-liberica:class-counter'
Adding layer 'paketo-buildpacks/bellsoft-liberica:java-security-properties'
Adding layer 'paketo-buildpacks/bellsoft-liberica:jre'
Adding layer 'paketo-buildpacks/bellsoft-liberica:jvmkill'
Adding layer 'paketo-buildpacks/bellsoft-liberica:link-local-dns'
Adding layer 'paketo-buildpacks/bellsoft-liberica:memory-calculator'
Adding layer 'paketo-buildpacks/bellsoft-liberica:openssl-security-provider'
Adding layer 'paketo-buildpacks/bellsoft-liberica:security-providers-configurer'
Adding layer 'paketo-buildpacks/executable-jar:class-path'
Adding 1/1 app layer(s)
Adding layer 'config'
*** Images (sha256:af858b3972b567fffa5792a9bed924c3638aba5eab4593c5a43364a67871efdc):
gcr.io/test-app
gcr.io/test-app:b1.20200609.213101
Adding cache layer 'paketo-buildpacks/bellsoft-liberica:jdk'
Adding cache layer 'paketo-buildpacks/maven:application'
Adding cache layer 'paketo-buildpacks/maven:cache'
===> COMPLETION
Build successful
Managing Images with kubectl
Build Services images can be created by applying the kpack image resources to cluster.
Use the default
service account for Build Service registry and git secrets.
Using a Build Service Builder with kubectl
The builder
field on the kpack Image spec describes the builder that will build the image.
Using a Custom Builder
builder: name: project-builder-name kind: CustomBuilder
name
: The name of the Custom Builder.
Using a Custom Cluster Builder
builder: name: builder-name kind: ClusterClusterBuilder
name
: The name of the cluster builder resource.
For more info on manging builders, see Managing Builders.
Warning: Unlike with kp
you will need to explicitly set the builder in the image configuration and it will not default to the default
builder.
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.
Image Status
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 describe image <image-name>
.
status:
conditions:
- lastTransitionTime: "2020-01-17T16:16:36Z"
status: "True"
type: Succeeded
latestImage: index.docker.io/sample/image@sha256:d3eb15a6fd25cb79039594294419de2328f14b443fa0546fa9e16f5214d61686
...
When a build fails its status will report the condition Succeeded=False.
status:
conditions:
- lastTransitionTime: "2020-01-17T16:13:48Z"
status: "False"
type: Succeeded
...