Build sources to containers

Cloud Run supports directly deploying source code, however, you can also build your source code into a container image and then deploy this container image to Cloud Run. You can use container images for any Cloud Run resource.

Common use cases for decoupling build and deploy operations:

  • Continuous Integration and Delivery: Developers author and push code to a source repository, a CI/CD system automatically builds this source code into a container, runs tests, and automatically deploys it to a staging environment.
  • Infrastructure as Code: Cloud Run resources that are managed using YAML or Terraform reference a container image URL. The source code written by developers need to be built into a container image.

You can use any system you want to build a container. This page describes the following ways to use Cloud Build to build container images:

Requirements for Cloud Run services

For Cloud Run services, you can use container images built with any tool capable of building container images, as long as they respect the container contract. In particular, your code must listen for HTTP requests on the port defined by the PORT environment variable. This PORT environment variable is automatically injected by Cloud Run into your container.

Before you begin

  • You need the Google Cloud CLI to run some of the commands in this page.

  • Create a repository at a supported container registry. To create an Artifact Registry repository, run:

        gcloud artifacts repositories create REPOSITORY \
        --repository-format=docker \
        --location=LOCATION \
        --description="DESCRIPTION" \
        --immutable-tags \
        --async

  • You can configure Docker to get access to Artifact Registry using the gcloud CLI credential helper: 

    gcloud auth configure-docker LOCATION-docker.pkg.dev
     Replace LOCATION with the region name of your container repository, for example, us-west2.

Build using a Dockerfile

Before building your sources into a container image ("containerizing") locally using Docker or using Cloud Build, you need a Dockerfile to be present along with your sources. The Hello World samples contain sample applications and Dockerfiles in many popular languages.

If you use Dockerfiles, you can use either of the following methods to build:

  • Build using Cloud Build
  • Build locally using Docker

Build using Cloud Build

You can build your image on Google Cloud by using Cloud Build:

  1. Navigate to the folder containing your sources and Dockerfile.

  2. Run the command:

    gcloud builds submit --tag IMAGE_URL

    Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

For tips on improving build performance, see Speeding up your builds

Build locally and push using Docker

If you have Docker installed locally, you can use docker build instead of using Cloud Build or Google Cloud's buildpacks.

To build your container image using Docker:

  1. Navigate to the folder containing your sources and Dockerfile.

  2. Run the command:

    docker build . --tag IMAGE_URL

    Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

    Note that if you are using a Mac with Apple silicon, you must specify --platform linux/amd64 in the command line.

  3. Push the container image to a supported container registry:

    docker push IMAGE_URL

    Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

To exclude local files from this process, follow the .dockerignore configuration file instructions.

Build using Google Cloud's buildpacks

Google Cloud's buildpacks is a set of CNCF-compatible Buildpacks that build source code into container images designed to run on Google Cloud container platforms, including Cloud Run.

For a list of supported languages, refer to the Google Cloud's buildpacks documentation

Build with Google Cloud's buildpacks using Cloud Build

To build with a Google Cloud's buildpacks:

  1. Navigate to the folder containing your sources.

  2. Run the command:

    gcloud builds submit --pack image=IMAGE_URL

    Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

  3. Wait for the build to complete.

Build with Google Cloud's buildpacks using the pack command line

To build using the pack command:

  1. If you haven't already done so, install Docker.

  2. If you haven't already done so, install pack.

  3. Navigate to the folder containing your sources.

  4. Run the following command to build and push to your supported container registry:

    pack build --publish IMAGE_URL

    Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

  5. Wait for pack to finish.

For more information, read the instructions under Building an Application.

What's next