Building container images

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.
  • If you want to use the gcloud commands in this page, install the gcloud command-line tool.
  • If you want to run the images, install Docker.

Build using a build config file

To build your Docker image using a build config file:

  1. In the same directory that contains your application source code and the Dockerfile, create a file named cloudbuild.yaml or cloudbuild.json.
  2. In the build config file:

    • Add a name field and specify the pre-built Docker image. The pre-built image is stored in the Container Registry at gcr.io/cloud-builders/docker. In the example config file below, the name field specifies that the pre-build Docker image is used by Cloud Build to execute the task indicated by the args field.
    • In the args field, add the arguments to build the image.

      YAML

      steps:
      - name: 'gcr.io/cloud-builders/docker'
        args: [ 'build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]', '.' ]
      

      JSON

      {
       "steps": [
        {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
              "build",
              "-t",
              "gcr.io/[PROJECT_ID]/[IMAGE_NAME]",
              "."
             ]
         }
         ]
       }
      

      Where:

      • [PROJECT_ID] is your Cloud project ID.
      • [IMAGE_NAME] is the name of your container image.
  3. 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.

    If you don't specify a [CONFIG_FILE_PATH] and [SOURCE_DIRECTORY] in the gcloud builds submit command, Cloud Build assumes that the config file and the source code are in the current working directory.

Build using 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 gcr.io/[PROJECT_ID]/[IMAGE_NAME]

Where:

  • [PROJECT_ID] is your Cloud project ID.
  • [IMAGE_NAME] is the name of your container image.

Storing images in Container 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 Container Registry after your build completes.
  • using the docker push command, which stores the image in Container 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 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 Container Registry after your build completes:

  1. In the same directory that contains your application source code and Dockerfile, create a file named cloudbuild.yaml or cloudbuild.json.
  2. 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 Container Registry. The following snippet shows a build config to build an image and store it in Container Registry:

    YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]', '.']
    images: ['gcr.io/[PROJECT_ID]/[IMAGE_NAME]']
    

    JSON

    {
    "steps": [
    {
        "name": "gcr.io/[PROJECT_ID]/[IMAGE_NAME]",
        "args": [
            "build",
            "-t",
            "gcr.io/[PROJECT_ID]/[IMAGE_NAME]",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/[PROJECT_ID]/[IMAGE_NAME]"
    ]
    }
    

    Where:

    • [PROJECT_ID] is your Cloud project ID.
    • [IMAGE_NAME] is the name of your container image.
  3. 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 Container Registry as part of your build flow:

  1. In the same directory that contains your application source code and Dockerfile, create a file named cloudbuild.yaml or cloudbuild.json.

  2. In your build config file, add a docker build step to build an image and then add another docker build step and pass arguments to invoke the push command:

    YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]', '.']
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]']
    

    JSON

    {
      "steps": [
       {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
              "build",
              "-t",
              "gcr.io/[PROJECT_ID]/[IMAGE_NAME]",
              "."
           ]
       },
       {
           "name": "gcr.io/cloud-builders/docker",
           "args": [
              "push",
              "gcr.io/[PROJECT_ID]/[IMAGE_NAME]"
            ]
       }
      ]
    }
    

    Where:

    • [PROJECT_ID] is your Cloud project ID.
    • [IMAGE_NAME] is the name of your container image.
  3. 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:

  1. In the same directory that contains your application source code and Dockerfile, create a file named cloudbuild.yaml or cloudbuild.json.
  2. In your build config file, after the step that builds the image, add a step to invoke the Docker push command and then add the images field:

    YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]', '.']
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/[PROJECT_ID]/[IMAGE_NAME]']
    images: ['gcr.io/[PROJECT_ID]/[IMAGE_NAME]']
    

    JSON

    {
        "steps": [
       {
           "name": "gcr.io/cloud-builders/docker",
           "args": [
               "build",
               "-t",
               "gcr.io/[PROJECT_ID]/[IMAGE_NAME]",
               "."
            ]
       },
       {
           "name": "gcr.io/cloud-builders/docker",
           "args": [
               "push",
               "gcr.io/[PROJECT_ID]/[IMAGE_NAME]"
            ]
       }
       ],
        "images": [
           "gcr.io/[PROJECT_ID]/[IMAGE_NAME]"
        ]
    }
    

    Where:

    • [PROJECT_ID] is your Cloud project ID.
    • [IMAGE_NAME] is the name of your container image.
  3. 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.

Run the Docker image

To verify that the image you built works as expected, you can run it using Docker.

  1. Configure Docker to use your Container Registry credentials when interacting with Container Registry (you are only required to do this once):

    gcloud auth configure-docker
    

    You'll see a message similar to the following:

    The following settings will be added to your Docker config file
    located at [/.docker/config.json]:
    
    {
      "credHelpers": {
        "gcr.io": "gcloud",
        "us.gcr.io": "gcloud",
        "eu.gcr.io": "gcloud",
        "asia.gcr.io": "gcloud",
        "staging-k8s.gcr.io": "gcloud",
        "marketplace.gcr.io": "gcloud"
      }
    }
    
    Do you want to continue (Y/n)?
    
  2. Type y and enter.

  3. Run the Docker image that you built before, where [PROJECT_ID] is your Cloud project ID:

    docker run gcr.io/[PROJECT_ID]/[IMAGE_NAME]
    

    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