Deploying to Cloud Run

This page explains how to automatically deploy Cloud Run (fully managed) services using Cloud Build. If you're new to Cloud Build, read the quickstarts and the build configuration overview first.

Cloud Run is a managed compute platform that enables you to run stateless containers in a serverless environment. Using Cloud Build, you can deploy container images from Container Registry to Cloud Run: you can deploy an existing image, build and deploy an image, or automate the deployment. For more information on Cloud Run, read the Cloud Run documentation.

Before you begin

  • Enable the Cloud Build, Cloud Run, Container Registry, and Resource Manager APIs.

    Enable the APIs

  • If you're deploying an existing prebuilt image, make sure the image is stored in Container Registry.

  • If you're building and then deploying the image, have your application source code ready.

  • To run the gcloud commands in this page, install the gcloud command-line tool.

Required IAM permissions

If your image is stored in the same Cloud project as the one you want to deploy to or if your image is public in Container Registry, you require the following IAM permissions:

  • Grant the Cloud Run Admin role to the Cloud Build service account:

    1. In the Cloud Console, go to the Cloud Build Settings page:

      Open the Settings page

    2. Locate the row with the Cloud Run Admin role and set its Status to ENABLED.

    3. In the Additional steps may be required pop-up, click Skip.

  • Grant the IAM Service Account User role to the Cloud Build service account on the Cloud Run runtime service account:

    1. In the Cloud Console, go to the Service Accounts page:

      Open the Service Accounts page

    2. In the list of members, locate and select [PROJECT_NUMBER]-compute@developer.gserviceaccount.com. This is the Cloud Run runtime service account.

    3. Click SHOW INFO PANEL in the top right corner.

    4. In the Permissions panel, click the Add Member button.

    5. In the New member field, enter the email address of the Cloud Build service account. This is of the form [PROJECT_NUMBER]@cloudbuild.gserviceaccount.com.

    6. In the Role dropdown, select Service Accounts, and then Service Account User.

    7. Click Save.

If your image is stored in a different Cloud project than the one you want to deploy to, you require additional IAM permissions as described in Deploying images from other GCP projects.

Deploying a prebuilt container image

Cloud Build enables you to use any publicly available container image to execute your tasks. You can do this by specifying the image URL in the name field in the Cloud Build config file.

Cloud Run provides a gcloud run deploy command, which enables you to deploy an image on Cloud Run. You can use the gcloud image as a build step in your config file to invoke gcloud commands within the image. Arguments passed to this build step are passed to the gcloud tool directly, allowing you to run any gcloud command in this image.

To deploy a prebuilt image from Container Registry:

  1. In your project root directory, create a build config file named cloudbuild.yaml or cloudbuild.json.

  2. In the build config file, add a step to invoke the gcloud run deploy command, which deploys the image to Cloud Run:

    YAML

    steps:
    # Deploy an image from Container Registry to Cloud Run
    - name: 'gcr.io/cloud-builders/gcloud'
      args:
      - 'run'
      - 'deploy'
      - '[SERVICE_NAME]'
      - '--image'
      - 'gcr.io/[PROJECT_ID]/[IMAGE]'
      - '--region'
      - '[REGION]'
      - '--platform'
      - 'managed'
      - '--allow-unauthenticated'
    

    JSON

    {
      "steps": [{
         "name": "gcr.io/cloud-builders/gcloud",
         "args": [
            "run",
            "deploy",
            "[SERVICE_NAME]",
            "--image",
            "gcr.io/[PROJECT_ID]/[IMAGE]",
            "--region",
             [
               "[REGION]"
             ],
             "--platform",
             "managed",
             "--allow-unauthenticated"
         ]
      }]
    }
    

    Where:

    • [SERVICE_NAME] is the name of the Cloud Run service to which you're deploying the image.
    • [PROJECT_ID] is the Google Cloud project ID where your image is stored.
    • [IMAGE] is the name of your image in Container Registry.
    • [REGION] is the region of the Cloud Run service.
  3. Start the build using the config file created in the previous step:

     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.

After successful completion, a message is displayed along with the URL of the deployed service.

Building and deploying a container

If you don't have a built image stored in Container Registry, Cloud Build enables you to build the container first, store the image in Container Registry, and then deploy the image to Cloud Run.

To build and deploy a container image:

  1. In your project root directory, create a config file named cloudbuild.yaml or cloudbuild.json.
  2. In the build config file, add docker build steps to build the image and push it to Container Registry, and then add a gcloud build step to invoke the gcloud run deploy command to deploy the image on Cloud Run:

    YAML

    steps:
    # Build the container image
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE]', '.']
    # Push the container image to Container Registry
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/[PROJECT_ID]/[IMAGE]']
    # Deploy container image to Cloud Run
    - name: 'gcr.io/cloud-builders/gcloud'
      args: ['run', 'deploy', '[SERVICE_NAME]', '--image', 'gcr.io/[PROJECT_ID]/[IMAGE]', '--region', '[REGION]', '--platform', 'managed', '--allow-unauthenticated']
    images:
    - gcr.io/[PROJECT_ID]/[IMAGE]
    

    JSON

    {
      "steps": [{
         "name": "gcr.io/cloud-builders/docker",
         "args": [
            "build",
            "-t",
            "gcr.io/[PROJECT_ID]/[IMAGE]",
            "."
          ]
      },
      {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
            "push",
            "gcr.io/[PROJECT_ID]/[IMAGE]"
          ]
      },
      {
          "name": "gcr.io/cloud-builders/gcloud",
          "args": [
             "run",
             "deploy",
             "[SERVICE_NAME]",
             "--image",
             "gcr.io/[PROJECT_ID]/[IMAGE]",
             "--region",
             "[REGION]",
             "--platform",
             "managed",
             "--allow-unauthenticated"
          ]
      }],
     "images": [
        "gcr.io/[PROJECT_ID]/[IMAGE]"
      ]
    }
    

    Where:

    • [SERVICE_NAME] is the name of the Cloud Run service to which you're deploying the image.
    • [PROJECT_ID] is your Google Cloud project ID where your image is stored.
    • [IMAGE] is the name of your image in Container Registry.
    • [REGION] is the region of the Cloud Run service.
  3. Start the build using the config file created in the previous step:

     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.

After successful completion, a success message is displayed along with the URL of the deployed service.

Continuous deployment

You can automate the deployment of your software to Cloud Run by creating Cloud Build triggers. You can configure your triggers to build and deploy images whenever you update your source code.

To automate your deployment to Cloud Run:

  1. In your repository root, add a config file with steps to build the image, push the image to Container Registry, and then invoke the gcloud run deploy command:

    YAML

    steps:
    # Build the container image
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA', '.']
    # Push the image to Container Registry
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA']
    # Deploy image to Cloud Run
    - name: 'gcr.io/cloud-builders/gcloud'
      args:
      - 'run'
      - 'deploy'
      - '[SERVICE_NAME]'
      - '--image'
      - 'gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA'
      - '--region'
      - '[REGION]'
      - '--platform'
      - 'managed'
    images:
    - gcr.io/[PROJECT_ID]/[IMAGE]
    

    JSON

    {
       "steps": [{
          "name": "gcr.io/cloud-builders/docker",
          "args": [
             "build",
             "-t",
             "gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA",
             "."
          ]
       },
       {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
             "push",
             "gcr.io/[PROJECT_ID]/[IMAGE]"
          ]
       },
       {
          "name": "gcr.io/cloud-builders/gcloud",
          "args": [
             "run",
             "deploy",
             "[SERVICE_NAME]",
             "--image",
             "gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA",
             "--region",
             "[REGION]",
             "--platform",
             "managed"
          ]
       }],
       "images": [
          "gcr.io/[PROJECT_ID]/[IMAGE]:$COMMIT_SHA"
        ]
    }
    

    Where:

    • [SERVICE_NAME] is the name for the Cloud Run service to which you're deploying the image.
    • [PROJECT_ID] is the Cloud project where the image is stored.
    • [IMAGE] is the name of your image in Container Registry.
    • [REGION] is the region for the Cloud Run service.
  2. Create a build trigger with the config file created in the previous step:

    1. Open the Triggers page in the Google Cloud Console:

      Open Triggers page

    2. Select your project from the project selector drop-down menu at the top of the page.

    3. Click Open.

    4. Click Create trigger.

      On the Create trigger page, enter the following settings:

      1. Enter a name for your trigger.

      2. Select the repository event to start your trigger.

      3. Select the repository that contains your source code and build config file.

      4. Specify the regex for the branch or tag name that will start your trigger.

      5. Build Configuration: Choose the build config file you created previously.

    5. Click Create to save your build trigger.

Anytime you push new code to your repository, you will automatically trigger a build and deploy to your Cloud Run service.

For more information on creating Cloud Build triggers, see Creating and managing build triggers.

Code examples

Here are some sample repositories, each of which contains a sample application and a build config file to deploy application to Cloud Run:

What's next