Using the Pivotal Build Service CLI
Page last updated:
This topic describes how to use the Pivotal Build Service CLI, pb
, to log in to Build Service and manage images, projects, and builds.
Log In to Build Service
After you configure and install Build Service, you can use the pb
CLI to target and log in to your Build Service installation.
For more information, see Installing and Configuring Build Service.
To target your Build Service installation and log in:
Target the API for your Build Service installation by running:
pb api set YOUR-BUILD-SERVICE-API
Where
YOUR-BUILD-SERVICE-API
is the URL for the API for your Build Service installation. For example,https://build-service.example.com
.Note: Use the
--skip-ssl-validation
flag if your Build Service installation targets a UAA that has a self-signed CA cert.Confirm that you targeted the correct Build Service installation by running:
pb api get
Log in to Build Service by running:
pb login
When prompted, enter the
username
andpassword
for UAA.
You can also pass your username and password to Build Service by specifying the environment variablesBUILD_SERVICE_USERNAME
andBUILD_SERVICE_PASSWORD
. The CLI defaults to using them if they exist in the environment.
Manage Projects
The following procedures describe how to manage projects and project members with the pb
CLI.
A project
is a Build Service entity that uses UAA to provide user access control to images, image configurations, and image builders. For more information, see Build Service Projects.
Create a Project
To create a new project:
Run:
pb project create PROJECT-NAME
Where
PROJECT-NAME
is a unique name for the project.
Targeting a Project
Projects map to Kubernetes namespaces. Because of this, you should not create projects with the same name as pre-existing Kubernetes namespaces.
The user who creates the project is added to the project as its first member. Because of this, you cannot access resources produced by Build Service globally across all the namespaces in the cluster.
To target your project:
Run:
pb project target PROJECT-NAME
Where
PROJECT-NAME
is the name of your project.
After you have targeted a project, Build Service assumes that the commands you run are for that project.
In order to target a different project, run the command again and specify a different project.
Add and Remove Project Members
All members of a project can add and remove project members.
Add Members to a Project
To add members to a project:
Target your project.
Run:
pb project user add UAA-USERNAME
Where
UAA-USERNAME
is the username of the user you want to add.
Remove Members from a Project
To remove members from a project:
Target your project.
Run:
pb project user remove UAA-USERNAME
Where
UAA-USERNAME
is the username of the user you want to remove.
Manage Image Registries for a Project
For a project to use an image registry in Build Service, you must associate an image registry and the image registry credentials with the project. If the source code for the image is saved in a repository, you must also associate the Git credentials with the project.
Build Service uses these credentials to deliver container image builds to the specified registry.
Note: The registry credentials must belong to a user with write
access on the registry.
Build Service supports the following image registries:
- Docker Hub
- GCR
- Harbor
- Artifactory
Associate an Image Registry with a Project
To associate an image registry and image registry credentials with a project:
Target the project with which you want to associate the image by running:
pb project target PROJECT-NAME
Where
PROJECT-NAME
is the name of the project that owns the image.Create a YAML file with the image registry location and credentials. Enter the following variables:
registry: REGISTRY-DOMAIN username: REGISTRY-USERNAME password: REGISTRY-PASSWORD
Where:
REGISTRY-DOMAIN
is the domain for the registry. Use the following guidance to complete theregistry
field, depending on your image registry:- Docker Hub: Enter
index.docker.io
. - 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
- Docker Hub: Enter
REGISTRY-USERNAME
andREGISTRY-PASSWORD
are the username and password of the image registry, respectively. You can include only one password for an image registry in the credentials YAML file.
Apply the image registry YAML file by running:
pb secrets registry apply -f PATH-TO-REGISTRY-CREDENTIALS-YAML
Where
PATH-TO-REGISTRY-CREDENTIALS-YAML
is the local path to the YAML file that you created in the previous step.
Change Image Registry Association and Credentials
To update the registry association and credentials for a project:
Modify the variables in your image registry YAML file.
- To change the project the registry is associated with, modify
project
. - To change the registry associated with the project, modify
registry
. - To change the credentials for the registry, modify
username
andpassword
.
- To change the project the registry is associated with, modify
Apply the image registry file by running:
pb secrets registry apply -f PATH-TO-REGISTRY-CREDENTIALS-YAML
Where
PATH-TO-REGISTRY-CREDENTIALS-YAML
is the local path to the YAML file that you created in the previous section.
Manage Git Repositories for a Project
To allow Build Service to execute builds against app source code in a private Git repository, you must add the Git username and password to the project that manages the source code.
As you apply YAML files that associate a Git repository and Git repository credentials with a project, the pb
CLI provides feedback indicating whether or not the commands succeeded.
Associate a Git Repository with a Project
To associate a Git repository and Git repository credentials with a project:
Note: If your git repository uses an access token, you can specify the token in the below password
field. For more information, see Creating a personal access token for the command line in the GitHub documentation.
Create a YAML file with the Git repository location and credentials. Enter the following variables:
repository: GIT-REPOSITORY username: GIT-USERNAME password: GIT-PASSWORD/TOKEN
Where:
GIT-REPOSITORY
is the URL of the GitHub repository.GIT-USERNAME
is the Git username used to access the GitHub repository.GIT-PASSWORD/TOKEN
is the password or access token used to access the GitHub repository.
Apply the Git repository file to the project by running:
pb secrets git apply -f PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
Where
PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
is the local path to the YAML file that you created in the previous step.
Change Git Repository Association and Credentials
To update the Git repository and credentials for a project:
Modify the variables in your Git repository YAML file.
- To change the Git repository associated with the project, modify
repository
. - To change the credentials for the Git repository, modify
username
andpassword
.
- To change the Git repository associated with the project, modify
Apply the Git repository credentials file by running:
pb secrets git apply -f PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
Where
PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
is the local path to the YAML file that you created in the previous step.
Delete Git Repository Credentials from a Project
To delete Git credentials from a project:
Run:
pb secrets git delete github.com
Delete a Project
This procedure describes how to delete a project using the pb
CLI.
Warning: If you delete a project, all registry credentials and Git secrets associated with that project are also deleted.
To delete a project:
Delete all image configurations in Build Service that are owned by the project. You cannot delete a project if the project owns any images on Build Service. To delete image configurations, see Delete an Image.
Run:
pb project delete PROJECT-NAME
Where
PROJECT-NAME
is the name of the project to delete.
Manage Images
The following procedures describe how to create and manage images in Build Service.
Image Configurations
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. Therevision
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.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 aname
and avalue
, for exampleBP_JAVA_VERSION
and8.*
.
- Includes an
image
: Defines the destination registry of the builds for the image. You must specify the credentials for the target registry in theregistries
section of the project configuration. For more information, see Manage Image Registries for a Project. The value forimage
must match the domain of one of the registries that you provided in the project configuration. Build Service uses the value ofimage.tag
to refer to the image after it is created. If you update the imagetag
, 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.
Apply 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.
The procedures in this section describe how to apply image configurations in Build Service that have source code saved in a Git repository or source code saved locally.
Apply an Image With Source Code in a Git Repository
To apply an image configuration to Build Service:
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 theregistry
field, depending on your image registry:- Docker Hub: Enter
index.docker.io
. - 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
- Docker Hub: Enter
PATH-TO-EXAMPLE-APP-IMAGE
is the local path to the image registry.
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.
Apply an Image With Local Source Code
To apply an image configuration that uses local source code:
Create an image configuration file that has no Git properties. For example:
build: env: - name: ENV-NAME value: ENV-VALUE image: tag: REGISTRY-DOMAIN/PATH-TO-EXAMPLE-APP
Where:
PATH-TO-EXAMPLE-APP
is the local path to an app.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 theregistry
field, depending on your image registry:- Docker Hub: Enter
index.docker.io
. - 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
- Docker Hub: Enter
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.
Apply an Image With Source Code In A Blob Store
To apply an image and reference source code that lives in a blobstore:
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/PATH-TO-EXAMPLE-APP
Where:
PATH-TO-EXAMPLE-APP
is the local path to an app.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 theregistry
field, depending on your image registry:- Docker Hub: Enter
index.docker.io
. - 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
- Docker Hub: Enter
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.
Note: Build Service v0.0.4 does not support polling functionality for source code that is stored in a blobstore. When you push new source code to the specified blobstore URL, Build Service cannot rebuild your app.
List Images
To list all the image configurations for the currently targeted project:
Run:
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 two 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.
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
, wherePATH-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
.
Monitor 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.
View All Builds for an Image
To list all the builds created for an image:
Run:
pb image builds IMAGE-TAG
Where
IMAGE-TAG
is the value of the fieldimage.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 --
- PENDING -- -- UNKNOWN --
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 or pending 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 runpb 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 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.
Digest
: Contains theSHA256
of the successfully built image. You can reference this SHA to run Docker commands such aspull
andinspect
.
View Build Details for an Image
To display detailed information about a build:
Run:
pb image build IMAGE-TAG -b BUILD-NUMBER
Where:
IMAGE-TAG
is the value of theimage.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 or pending 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 runpb 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 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.
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.
- For a build created from a Git commit:
Buildpacks
: A list of buildpacks the build used.
View Logs for a Build
To view logs for a build:
Run:
pb image logs IMAGE-TAG -b BUILD-NUMBER
Where:
IMAGE-TAG
is the value of theimage.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]
View 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:
Run:
pb image logs IMAGE-TAG -b BUILD-NUMBER -f
Where:
IMAGE-TAG
is the value of theimage.tag
field in the image configuration YAML file.BUILD-NUMBER
is the number of the build with the logs you want to view.
Delete 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:
Run:
pb image delete IMAGE-TAG
Where
IMAGE-TAG
is the value of theimage.tag
field in the image configuration YAML file.
When you successfully delete an image, you see this message:
Successfully deleted image IMAGE-TAG