This page describes how to configure Cloud Build to build and store Docker images. If you're new to Cloud Build, read the quickstarts and the build configuration overview first.
Cloud Build provides pre-built images that you can reference in a Cloud Build config file to execute your tasks. These images are supported and maintained by Google Cloud. You can use the supported, pre-built Docker image to execute Docker commands and build Docker images.
Before you begin
The instructions on this page assume that you are familiar with Docker. In addition:
- Have your application source code along with
Dockerfile
handy. - Have a Docker repository for storing images in Artifact Registry, or create a new repository.
- If you want to use the
gcloud
commands in this page, install the Google Cloud CLI. - If you want to run the images, install Docker
- If you want to sign the images with cosign, follow the instructions in Authorize service-to-service access to create a user-specified service account and grant the permissions required to generate ID tokens.
Build with a build config file
To build your Docker image using a build config file:
- In the same directory that contains your application source code,
create a file named
cloudbuild.yaml
orcloudbuild.json
. In the build config file:
- Add a
name
field and specify the pre-built Docker image. The pre-built image is stored atgcr.io/cloud-builders/docker
. In the example config file below, thename
field specifies that the pre-built Docker image is used by Cloud Build to execute the task indicated by theargs
field. In the
args
field, add the arguments to build the image.YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.' ]
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] } ] }
Replace the placeholder values in the above build config with the following:
LOCATION
: the regional or multi-regional location of your Docker repository in Artifact Registry.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Docker repository in Artifact Registry.IMAGE_NAME
: the name of your container image.If your
Dockerfile
and source code are in different directories, add-f
and the path to theDockerfile
to the list of arguments in theargs
field:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '-f', 'DOCKERFILE_PATH', '.' ]
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", '-f', 'DOCKERFILE_PATH', "." ] } ] }
Replace the placeholder values in the above build config with the following:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.DOCKERFILE_PATH
: path to yourDockerfile
.
- Add a
Start the build using the build config file:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
Replace the placeholder values in the above command with the following:
CONFIG_FILE_PATH
: the path to the build config file.SOURCE_DIRECTORY
: the path or URL to the source code.
If you don't specify a
CONFIG_FILE_PATH
andSOURCE_DIRECTORY
in thegcloud builds submit
command, Cloud Build assumes that the config file and the source code are in the current working directory.
Build with a Dockerfile
Cloud Build allows you to build a Docker image using just a
Dockerfile
. You don't require a separate build config file.
To build using a Dockerfile
, run the following command from the directory
containing your source code and the Dockerfile
:
gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME
Replace the placeholder values in the above command with the following:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.
Build with Google Cloud's buildpacks
Cloud Build allows you to build an image without a Dockerfile or a build config file. You can do this using Google Cloud's buildpacks.
To build using buildpacks, run the following command from the directory containing your source code:
gcloud builds submit --pack builder=BUILDPACK_BUILDER, \
env=ENVIRONMENT_VARIABLE, \
image=IMAGE_NAME
Replace the placeholder values in the above commands with the following:
- BUILDPACK_BUILDER: the buildpacks builder to use.
If you don't specify a builder, Cloud Build uses
gcr.io/buildpacks/builder
by default. - ENVIRONMENT_VARIABLE: any environment variables for your build.
- IMAGE: the URL of the image in Artifact Registry. The image URL must be in the format LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME.
Here are some example commands:
Running a build using the default
gcr.io/buildpacks/builder
to create the imageus-docker.pkg.dev/gcb-docs-project/containers/gke/hello-app
:gcloud builds submit --pack image=us-docker.pkg.dev/gcb-docs-project/containers/gke/hello-app
Passing multiple environment variables to your build using
^--^
as a separator. For more information about escaping arguments, seegcloud topic escaping
.gcloud builds submit --pack \ ^--^image=gcr.io/my-project/myimage--env=GOOGLE_ENTRYPOINT='java -jar target/myjar.jar',GOOGLE_RUNTIME_VERSION='3.1.301'
Configuring triggers to use buildpacks: In addition to building using the command line, you can configure triggers to use buildpacks to build your image automatically. To learn more, see Creating and managing build triggers.
Different ways of storing images in Artifact Registry
You can configure Cloud Build to store your built image in one of the following ways:
- using the
images
field, which stores the image in Artifact Registry after your build completes. - using the
docker push
command, which stores the image in Artifact Registry as part of your build flow.
The difference between using the images
field and the Docker push
command is
that if you use the images
field, the stored image will be displayed in the
build results. This includes the Build description page for a build in the
Google Cloud console, the results of
Build.get()
,
and the results of gcloud builds list
. However, if you use the
Docker push
command to store the built image, the image will not be displayed
in the build results.
If you want to store the image as part of your build flow and want to display the
image in the build results, use both the Docker push
command and the images
field in your build config file.
To store a container image in Artifact Registry after your build completes:
- If the target repository does not exist, create a new repository.
- In the same directory that contains your application source code and
Dockerfile
, create a file namedcloudbuild.yaml
orcloudbuild.json
. In your build config file, add a build step to build an image and then add an
images
field specifying the built image. This stores the image in Artifact Registry. The following snippet shows a build config to build an image and store it in Artifact Registry:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.' ] images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] } ], "images": [ "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ] }
Where:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.
Start the build using the build config file:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
Where:
CONFIG_FILE_PATH
is the path to the build config file.SOURCE_DIRECTORY
is the path or URL to the source code.
To store the image in Artifact Registry as part of your build flow:
In the same directory that contains your application source code and
Dockerfile
, create a file namedcloudbuild.yaml
orcloudbuild.json
.In your build config file, add a
docker
build step to build an image and then add anotherdocker
build step and pass arguments to invoke thepush
command:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.'] - name: 'gcr.io/cloud-builders/docker' args: ['push', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] }, { "name": "gcr.io/cloud-builders/docker", "args": [ "push", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ] } ] }
Where:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.
Start the build using the build config file:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
Where:
CONFIG_FILE_PATH
is the path to the build config file.SOURCE_DIRECTORY
is the path or URL to the source code.
To store an image as part of your build flow and to display the image in the build results:
- In the same directory that contains your application source code and
Dockerfile
, create a file namedcloudbuild.yaml
orcloudbuild.json
. In your build config file, after the step that builds the image, add a step to invoke the Docker
push
command and then add theimages
field:YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.'] - name: 'gcr.io/cloud-builders/docker' args: ['push', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME'] images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] }, { "name": "gcr.io/cloud-builders/docker", "args": [ "push", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ] } ], "images": [ "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ] }
Where:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.
Start the build using the build config file:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
Where:
CONFIG_FILE_PATH
is the path to the build config file.SOURCE_DIRECTORY
is the path or URL to the source code.
Sign container images with cosign
If you're storing images in Artifact Registry, you can add another layer of security by using the cosign tool to create a record of which service account is used to initiate a build. Backed by the OpenID Connect (OIDC) standard, auditors can use that record to verify that an image was built by a trusted service account.
The following steps demonstrate how to use your cloudbuild.yaml
config file
to get an identity token and sign your container image.
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
id: 'tag-and-push'
script: |
#!/bin/sh
set -e
docker build -t $_IMAGE .
docker push "$_IMAGE"
docker inspect $_IMAGE --format "$_IMAGE@{{.Id}}" >image_with_digest
- name: 'gcr.io/cloud-builders/gcloud'
id: 'generate-token'
script: |
#!/bin/sh
set -e
gcloud auth print-identity-token --audiences=sigstore > token
- name: 'gcr.io/cloud-builders/docker'
id: 'sign-image'
script: |
#!/bin/sh
set -e
docker run \
--network=cloudbuild \
--mount source=home-volume,target=/builder/home \
--rm \
-e SIGSTORE_NO_CACHE=true \
-e HOME=/builder/home \
gcr.io/projectsigstore/cosign \
sign --identity-token=$(cat token) $(cat image_with_digest) -y
service_account: '$_SERVICE_ACCOUNT'
artifacts:
images:
- $_IMAGE
substitutions:
_IMAGE: 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME'
_SERVICE_ACCOUNT_ID: 'SERVICE_ACCOUNT_ID'
_SERVICE_ACCOUNT: projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}
options:
env:
- '_IMAGE=$_IMAGE'
dynamic_substitutions: true
logging: CLOUD_LOGGING_ONLY
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"id": "tag-and-push",
"script": "#!/bin/sh set -e \ndocker build -t $_IMAGE . \ndocker push \"$_IMAGE\""
},
{
"name": "gcr.io/cloud-builders/gcloud",
"id": "generate-token-and-get-digest",
"script": "#!/bin/sh set -e \ngcloud auth print-identity-token --audiences=sigstore > token \ngcloud container images describe \"$_IMAGE\" --format=\"value(image_summary.fully_qualified_digest)\" > image_with_digest"
},
{
"name": "gcr.io/projectsigstore/cosign",
"id": "sign-image",
"script": "#!/busybox/sh cosign sign --identity-token=$(cat token) $(cat image_with_digest) -y",
"env": [
"SIGSTORE_NO_CACHE=true"
]
}
],
"service_account": "$_SERVICE_ACCOUNT",
"artifacts": {
"images": [
"$_IMAGE"
]
},
"substitutions": {
"_IMAGE": "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
"_SERVICE_ACCOUNT_ID": "SERVICE_ACCOUNT_ID",
"_SERVICE_ACCOUNT": "projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}"
},
"options": {
"env": [
"_IMAGE=$_IMAGE"
],
"dynamic_substitutions": true,
"logging": "CLOUD_LOGGING_ONLY"
}
}
Where:
LOCATION
is the regional or multi-regional location of the repository where the image is stored, for exampleus-east1
orus
.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
is the name of the repository where the image is stored.IMAGE_NAME
is the image's name.SERVICE_ACCOUNT_ID
is the email address of the user-specified service account you want to run your build. For example, a service account email address looks like:service-account-name@project-id.iam.gserviceaccount.com
.
To verify the signature, install cosign
on your local machine, then run the cosign verify
command:
cosign verify \
--certificate-identity=SERVICE_ACCOUNT_ID \
--certificate-oidc-issuer=https://accounts.google.com \
IMAGE
Where:
SERVICE_ACCOUNT_ID
is the email address of the trusted service account that you expect to have been used to build the container image.IMAGE
is the full image name including the sha256 image digest.
Run the Docker image
To verify that the image you built works as expected, you can run it using Docker.
Configure Docker to use your Artifact Registry credentials when interacting with Artifact Registry. (You are only required to do this once.) Use the following command to authenticate using the gcloud credential helper.
gcloud auth configure-docker HOSTNAME-LIST
Where HOSTNAME-LIST is a comma-separated list of repository hostnames to add to the credential helper configuration.
For example, to add the regions
us-central1
andasia-northeast1
, run the command:gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Run the Docker image that you built before:
docker run LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME
Where:
LOCATION
: the regional or multi-regional location for your repository.PROJECT_ID
: your Google Cloud project ID.REPOSITORY
: the name of your Artifact Registry repository.IMAGE_NAME
: the name of your container image.
You will see an output similar to the following:
Hello, world! The time is Fri Feb 2 16:09:54 UTC 2018.
What's next
- Learn how to build Java applications.
- Learn how to build Python applications.
- Learn how to build Go applications.
- Learn how to store build artifacts in Cloud Storage.
- Learn how to store build artifacts in Artifact Registry.
- Learn how to troubleshoot build errors.