Managing Images and Builds

Page last updated:

Images provide a configuration for build service to build and maintain a docker image utilizing Tanzu Buildpacks 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.

Creating Images

Prerequisites:

  • Access to a cluster running Build Service.
  • pb project target the namespace or project you want to create an image.
  • Configured write secrets for your docker registry.

Image Configuration

To create an image, you must create an image configuration YAML that includes the following properties:

  • source: Defines the Git location of the code that the image is built against. The revision 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.

  • build: Defines additional configuration for your app such as buildpack version numbers.

    • Includes an env property that supplies values to the build by setting environment variables.
    • Each env environment variable is an object with a name and a value, for example BP_JAVA_VERSION and 8.*.
  • image: Defines the destination registry of the builds for the image. You must specify the credentials for the target registry in the registries section of the project configuration. For more information, see Manage Image Registries for a Project. The value for image must match the domain of one of the registries that you provided in the project configuration. Build Service uses the value of image.tag to refer to the image after it is created. If you update the image tag, Build Service creates a new image.

For more information about creating and applying image configurations for apps with source code in GitHub or source code saved locally, see Apply Image Configurations.

Applying Image Configurations

Build Service supports builds against apps with source code that is saved in a Git repository or saved on your local machine. You can specify only one location for app source code.

Applying an Image With Source Code in a Git Repository

To apply an image configuration to Build Service:

  1. Create an image configuration YAML file. For example:

    source:
      git:
        url: https://github.com/PATH-TO-EXAMPLE-APP
        revision: master
    build:
      env:
      - name: ENV-NAME
        value: ENV-VALUE
    image:
      tag: REGISTRY-DOMAIN/PATH-TO-EXAMPLE-APP-IMAGE
    

    Where:

    • PATH-TO-EXAMPLE-APP is the path to an app on GitHub.
    • ENV-NAME is the name of your build environment.
    • ENV-VALUE is the value of your build environment.
    • REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
      • Docker Hub: No registry required.
      • GCR: Enter gcr.io.
      • Harbor: Enter the domain that is specific to your deployment of the registry.
      • Artifactory: Enter the domain that is specific to your deployment of the registry
    • PATH-TO-EXAMPLE-APP-IMAGE is the local path to the image registry.
  2. Apply the image configuration by running:

    pb image apply -f PATH-TO-IMAGE-CONFIGURATION
    

    Where PATH-TO-IMAGE-CONFIGURATION is the local path where you saved the image configuration YAML file.

Applying an Image With Local Source Code

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

To apply an image configuration that uses local source code:

  1. Create an image configuration file that has no Git properties. For example:

    build:
      env:
      - name: ENV-NAME
        value: ENV-VALUE
    image:
      tag: REGISTRY-DOMAIN/REST-OF-TAG
    

    Where:

    • ENV-NAME is the name of your build environment.
    • ENV-VALUE is the value of your build environment.
    • REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
      • Docker Hub: No registry required.
      • GCR: Enter gcr.io.
      • Harbor: Enter the domain that is specific to your deployment of the registry.
      • Artifactory: Enter the domain that is specific to your deployment of the registry
    • REST-OF-TAG is the rest of the tag for your image
  2. Apply the image configuration by running:

    pb image apply -f PATH-TO-IMAGE-CONFIGURATION/IMAGE-CONFIGURATION.yaml -p /PATH-TO-APP-DIRECTORY
    

    Where:

    • PATH-TO-IMAGE-CONFIGURATION is the local path to the image configuration YAML file.
    • IMAGE-CONFIGURATION is the name of the image configuration YAML file.
    • PATH-TO-APP-DIRECTORY is the local path to the app directory.

Note: To use this feature, the user must have access to the Docker registry specified by the tag property on the local machine.

Applying an Image With Source Code In A Blob Store

To apply an image and reference source code that lives in a blobstore:

  1. Create an image configuration file that has no Git properties. For example:

    build:
      source:
        blob:
          url: https://storage.blob.com/my-org/myapp.jar
      env:
      - name: ENV-NAME
        value: ENV-VALUE
    image:
      tag: REGISTRY-DOMAIN/REST-OF-TAG
    

    Where:

    • ENV-NAME is the name of your build environment.
    • ENV-VALUE is the value of your build environment.
    • REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
      • Docker Hub:No registry required.
      • GCR: Enter gcr.io.
      • Harbor: Enter the domain that is specific to your deployment of the registry.
      • Artifactory: Enter the domain that is specific to your deployment of the registry
    • REST-OF-TAG is the rest of the tag for your image
  2. Apply the image configuration by running:

    pb image apply -f PATH-TO-IMAGE-CONFIGURATION/IMAGE-CONFIGURATION.yaml
    

    Where:

    • PATH-TO-IMAGE-CONFIGURATION is the local path to the image configuration YAML file.
    • IMAGE-CONFIGURATION is the name of the image configuration YAML file.

Applying an Image With A Custom Builder

Users can use any of the available builders with any of the source types (git, blob, or local).

To apply an image and reference a custom builder:

  1. Create an image configuration file that has builder properties:

    build:
      source:
        git:
          url: https://github.com/PATH-TO-EXAMPLE-APP
          revision: master
    builder:
      name: BUILDER-NAME
      scope: Project OR Cluster
    image:
      tag: REGISTRY-DOMAIN/REST-OF-TAG
    
  2. Apply the image configuration by running:

    pb image apply -f /PATH-TO-IMAGE-CONFIGURATION/IMAGE-CONFIGURATION.yaml
    

    Where:

    • PATH-TO-IMAGE-CONFIGURATION is the local path to the image configuration YAML file.
    • IMAGE-CONFIGURATION is the name of the image configuration YAML file.

Listing Images

To list all the image configurations for the currently targeted project:

pb image list

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

Project: some-project

Images
------
first/image:tag
second/image:tag
third/image:tag

Image Rebuilds

Rebuilds happen in three ways. An imperative rebuild occurs when you make edits to the image configuration and run pb image apply. An automatic rebuild occurs when build inputs change, without you editing the image configuration itself. Finally, a user can trigger a rebuild manually.

You can initiate an imperative rebuild in these ways:

  • You update the commit, branch, Git repository, or build fields on the image’s configuration file and re-apply it by running pb image apply.

  • You upload a new copy of the local source code by running pb image apply -p PATH-TO-SOURCE, where PATH-TO-SOURCE is the source code path.

For more information, see Apply Image Configurations.

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 Pivotal Network includes the latest buildpacks contained in a builder image.
    • When upgrading PBS, you must relocate new buildpack versions over to your container registry.
  • There is a new commit on a branch or tag Build Service is tracking.

  • There is a new base OS image available, such as cflinuxfs3.

Trigger an Image Rebuild

You can initiate a manual rebuild using pb:

pb image trigger IMAGE-TAG

This is useful for debugging image builds.

Monitoring Builds for an Image

The procedures in this section describe how to view information and logs for image builds.

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

To view logs for a build, you must provide the build number. You cannot view logs for a build by referencing the image digest.

Viewing All Builds for an Image

To list all the builds created for an image:

pb image builds IMAGE-TAG

Where IMAGE-TAG is the value of the field image.tag in the image configuration YAML file.

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

Build    Status    Started Time           Finished Time          Reason    Digest
-----    ------    ------------           -------------          ------    ------
    1    SUCCESS   2019-09-09 21:55:27    2019-07-08 21:55:54    CONFIG    *************************************************
    2    SUCCESS   2019-09-09 21:56:55    2019-07-08 21:57:40    COMMIT    *************************************************
    3    SUCCESS   2019-09-09 21:57:55    2019-07-08 21:58:40    STACK     *************************************************
    4    FAILED    2019-09-09 21:58:55    2019-07-08 21:59:40    CONFIG+   --
    5    BUILDING  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.

  • Started Time: Describes when a build started.

  • Finished Time: 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 run pb image apply.
    • COMMIT: Occurs when new source code is committed to a branch or tag 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 pb 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, and BUILDER.

    • STACK: Occurs when a new base OS image, called a run image, is available.
  • Digest: Contains the SHA256 of the successfully built image. You can reference this SHA to run Docker commands such as pull and inspect.

Viewing the Status of an Image

When a user creates an image using the above workflow, they are also creating an image configuration against which a stream of images will be built.

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

pb image status IMAGE-TAG

Where IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.

The following is an example output of this command:

Image
-----
Status:          NOT READY
Message:         N/A
Latest Image:    gcr.io/myapp@sha256:9d7b1fbf7f5cb0f8efe797f30e598b5e38bb1c08ada143d4c96e4f78111a9239

Last Successful Build
---------------------
ID:        1
Reason:    CONFIG

Last Failed Build
-----------------
ID:        2
Reason:    COMMIT

Viewing Build Details for an Image

To display retrieve a detailed Bill of Materials for a particular build:

pb image build IMAGE-TAG -b BUILD-NUMBER

Where:

  • IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
  • BUILD-NUMBER is the number of the build you want to inspect.

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

------------------
Retrieving information for image "gcr.io/myapp" - build 1
------------------
STATUS
     Status:     SUCCESS
     Reasons:    Config
     Image:      gcr.io/myapp@sha256:f87b614257af05c3301c1554c4f15131793caec3adf55e45d2c612e90445765a
------------------
BUILD DETAILS
     Run Image:  cloudfoundry/cnb:run@sha256:asdas098asdas
     Builder:    cloudfoundry/cnb:bionic@sha256:grtewwads0asdvf09asdf

     Source:
         Git:        http://github.com/myapp
         Revision:   ad123ad
     Buildpacks:
         Id:         io.java.etc
         Version:    123

         Id:         io.kotlin.etc
         Version:    321

------------------

The following describes the fields in the example output:

  • 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 run pb image apply.
    • COMMIT: Occurs when new source code is committed to a branch or tag 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 pb 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, and BUILDER.

    • STACK: Occurs when a new base OS image (called a run image) is available.
  • Image: The full image tag for the app image produced by the build.

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

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

  • Source: This field contains one of the following:

    • For a build created from a Git commit:
      • Git: The Git repository URL.
      • Revision: The commit SHA.
    • For a build created from local source code:
      • Local Source: Indicates that the source code was pushed from a development workstation.
    • For a build created from a blob:
      • Blob: The blob URL.
  • Buildpacks: A list of buildpacks the build used.

Viewing Logs for a Build

To view logs for a build:

pb image logs IMAGE-TAG -b BUILD-NUMBER

Where:

  • IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
  • BUILD-NUMBER is the number of the build with the logs you want to view.

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

[build-step-credential-initializer] {"level":"info","ts":1562684107.3441668,"logger":"fallback-logger","caller":"creds-init/main.go:40","msg":"Credentials initialized.","commit":"002a41a"}
[build-step-credential-initializer]
[build-step-git-source-0] git-init:main.go:81: Successfully cloned "https://github.com/buildpack/sample-java-app" @ "abde24efc17802b7e2b3814e0ead63a460e66f5f" in path "/workspace"
[build-step-git-source-0]
[build-step-prepare]
[build-step-detect] Trying group 1 out of 3 with 27 buildpacks...
[build-step-detect] ======== Results ========
[build-step-detect] skip: Cloud Foundry Archive Expanding Buildpack
[build-step-detect] pass: Pivotal OpenJDK Buildpack
[build-step-detect] pass: Pivotal Build System Buildpack
[build-step-detect] pass: Cloud Foundry Spring Boot Buildpack
[build-step-detect] pass: Cloud Foundry Apache Tomcat Buildpack
...
[build-step-detect] skip: Cloud Foundry JMX Buildpack
[build-step-detect] pass: Cloud Foundry Spring Auto-reconfiguration Buildpack
[build-step-detect]
[build-step-restore] Restoring cached layer 'io.pivotal.openjdk:openjdk-jdk'
...
[build-step-restore] Restoring cached layer 'org.cloudfoundry.springboot:spring-boot'
[build-step-restore]
[build-step-analyze] Analyzing image 'registry.com/sample/demo@sha256:8ff708081ee10f7039f77275f1e6eb6359cae8d90028c79a5c493ced0dc63f68'
[build-step-analyze] Using cached layer 'io.pivotal.openjdk:openjdk-jdk'
...
[build-step-analyze] Rewriting metadata for layer 'org.cloudfoundry.springboot:spring-boot'
[build-step-analyze] Writing metadata for uncached layer 'io.pivotal.clientcertificatemapper:client-certificate-mapper'
[build-step-analyze] Writing metadata for uncached layer 'org.cloudfoundry.springautoreconfiguration:auto-reconfiguration'
[build-step-analyze]
[build-step-build]
[build-step-build] Pivotal OpenJDK Buildpack 1.0.0-M9
[build-step-build]   OpenJDK JDK 11.0.3: Reusing cached layer
[build-step-build]   OpenJDK JRE 11.0.3: Reusing cached layer
[build-step-build]   JVMKill Agent 1.16.0: Reusing cached layer
[build-step-build]   Class Counter 1.0.0-M9: Reusing cached layer
[build-step-build]   Memory Calculator 4.0.0: Reusing cached layer
[build-step-build]
...
[build-step-build]     task:        java -cp $CLASSPATH $JAVA_OPTS io.buildpacks.example.sample.SampleApplication
[build-step-build]     web:         java -cp $CLASSPATH $JAVA_OPTS io.buildpacks.example.sample.SampleApplication
[build-step-build]
[build-step-build] Pivotal Client Certificate Mapper Buildpack 1.0.0-M9
[build-step-build] Cloud Foundry Spring Auto-reconfiguration Buildpack 1.0.0-M9
[build-step-build]   Spring Auto-reconfiguration 2.7.0: Reusing cached layer
[build-step-build]
[build-step-export] Reusing layers from image 'index.docker.io/matthewmcnew/demo@sha256:8ff708081ee10f7039f77275f1e6eb6359cae8d90028c79a5c493ced0dc63f68'
[build-step-export] Reusing layer 'app' with SHA sha256:02e0070ce11bac1829174ec1296dcb1f3f04a4c30a958e2c41ad5498f78898fe
...
[build-step-export] Reusing layer 'org.cloudfoundry.springautoreconfiguration:auto-reconfiguration' with SHA sha256:93d94baf6d0dfc4981eb7d8ddfc4ae51f5c13cf87789b64ae8c4b015318a1b43
[build-step-export] *** Images:
[build-step-export]       registry.com/sample/demo:latest - succeeded
[build-step-export]       registry.com/sample/demo:b2.20190709.145448 - succeeded
[build-step-export]
[build-step-export] *** Digest: sha256:48a4ca8e4d8e8a9af26437588d0ce0e9d5c09b53aeb3ef64230a3d58d4b0dc90
[build-step-export]
[build-step-cache] Reusing layer 'io.pivotal.openjdk:openjdk-jdk' with SHA sha256:5554c7c06a266eb44a7cbdf0ecfaa14070e21af2b0bdfd1edd3b96f5168cd511
[build-step-cache] Reusing layer 'io.pivotal.buildsystem:build-system-cache' with SHA sha256:3b03fdd870a2dc1e924a040b604c25b76efafc1324ceb08eae8eae686fc3a940
...
[build-step-cache] Reusing layer 'org.cloudfoundry.springboot:spring-boot' with SHA sha256:effa8b80729cafa9f9a01b21a4badb5203510de0bb2e6b309ffd2593b0a28de7
[build-step-cache]

Viewing Logs for a Running Build

You can stream logs that show the progress of a build. The logs terminate when the build completes.

To view logs for a running build:

pb image logs IMAGE-TAG -b BUILD-NUMBER -f

Where:

  • IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
  • BUILD-NUMBER is the number of the build with the logs you want to view.

Deleting an Image

This procedure describes how to delete a Build Service image.

Warning: Deleting an image also deletes all the builds that the image owns. It does not delete the images generated by those builds.

To delete an image:

pb image delete IMAGE-TAG

Where IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.

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

Successfully deleted image IMAGE-TAG

Managing Images with kubectl

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

The default service account should be used to utilize 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 a Project Builder

    builder:
        name: project-builder-name
        kind: CustomBuilder
    
    • name: The name of the project scoped builder.
  • Using a a 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 pb you will need to explicitly set the builder in the image configuration and it will not default to the default builder.

Using Secrets

The default service account should be used to utilize 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-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
  ...