Deploying to Cloud Run

This page explains how to automatically deploy Cloud Run 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 and Artifact 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

  • 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:

Fully Managed

To deploy to Cloud Run (fully managed) grant the Cloud Run Admin and Service Account User roles to the Cloud Build service account:

  1. Open the Cloud Build settings page in the Cloud Console:

    Go to the Cloud Build settings page

  2. In the Service account permissions panel, set the status of the Cloud Run Admin role to ENABLED:

    Screenshot of the Service account permissions page

  3. In the Additional steps may be required pop-up, click GRANT ACCESS TO ALL SERVICE ACCOUNTS.

Anthos on Google Cloud

To deploy to Cloud Run for Anthos, grant the Kubernetes Engine Developer role to the Cloud Build service account:

  1. Open the Cloud Build settings page in the Cloud Console:

    Go to the Cloud Build settings page

  2. In the Service account permissions panel, set the status of the Kubernetes Engine Developer role to ENABLED:

    Screenshot of the Service account permissions page

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.

Building and deploying a container

Cloud Build enables you to build the container image, store the built 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.

  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:

    Fully Managed

    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/google.com/cloudsdktool/cloud-sdk'
      entrypoint: gcloud
      args: ['run', 'deploy', 'SERVICE-NAME', '--image', 'gcr.io/PROJECT_ID/IMAGE', '--region', 'REGION', '--platform', 'managed']
    images:
    - gcr.io/PROJECT_ID/IMAGE
    

    Where:

    • SERVICE-NAME is the name of the Cloud Run service.
    • REGION is the region of the Cloud Run service you are deploying.
    • PROJECT_ID is your Google Cloud project ID where your image is stored.
    • IMAGE is the name of your image in Container Registry.

    Anthos on Google Cloud

    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/google.com/cloudsdktool/cloud-sdk'
      entrypoint: gcloud
      args: ['run', 'deploy', 'SERVICE-NAME', '--image', 'gcr.io/PROJECT_ID/IMAGE', '--cluster', 'CLUSTER', '--cluster-location', 'CLUSTER_LOCATION', '--platform', 'gke']
    images:
    - gcr.io/PROJECT_ID/IMAGE
    

    Where:

    • SERVICE-NAME is the name of the Cloud Run service.
    • CLUSTER is the name of your Cloud Run for Anthos on Google Cloud cluster.
    • CLUSTER_LOCATION is the location of your Cloud Run for Anthos on Google Cloud cluster.
    • PROJECT_ID is your Google Cloud project ID where your image is stored.
    • IMAGE is the name of your image in Container Registry.
  3. Navigate to your project root directory, and run:

     gcloud builds submit
    

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:

    Fully Managed

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

    Where:

    • SERVICE-NAME is the name of the Cloud Run service.
    • REGION is the region of the Cloud Run service you are deploying.

    Anthos on Google Cloud

     steps:
     # build the container image
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 'gcr.io/$PROJECT_ID/SERVICE-NAME:$COMMIT_SHA', '.']
     # push the container image to Container Registry
     - name: 'gcr.io/cloud-builders/docker'
       args: ['push', 'gcr.io/$PROJECT_ID/SERVICE-NAME:$COMMIT_SHA']
     # Deploy container image to Cloud Run
     - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
       entrypoint: gcloud
       args:
       - 'run'
       - 'deploy'
       - 'SERVICE-NAME'
       - '--image'
       - 'gcr.io/$PROJECT_ID/SERVICE-NAME:$COMMIT_SHA'
       - '--cluster'
       - 'CLUSTER'
       - '--cluster-location'
       - 'CLUSTER_LOCATION'
       - '--platform'
       - 'gke'
     images:
     - 'gcr.io/$PROJECT_ID/SERVICE-NAME:$COMMIT_SHA'
    

    Where:

    • SERVICE-NAME is the name of the Cloud Run service.
    • CLUSTER is the name of your Cloud Run for Anthos on Google Cloud cluster.
    • CLUSTER_LOCATION is the location of your Cloud Run for Anthos on Google Cloud cluster.

    The use of the $COMMIT_SHA substitution variable is populated by Cloud Build when triggered from a Git repository.

  2. Create a build trigger with the config file created in the previous step:

    1. Open the Triggers page:

      Go to the Triggers page

    2. Click Create Trigger.

    3. In the Name field, enter a name for your trigger.

    4. Under Event, select the repository event to start your trigger.

    5. Under Source, select your repository and the branch or tag name that will start your trigger. For more information on specifying which branches to autobuild, see Creating a build trigger.

    6. Under Build configuration, select Cloud Build configuration file.

    7. In the Cloud Build configuration file location field, type cloudbuild.yaml after the /.

    8. Click Create to save your build trigger.

  3. You are finished! From now on, whenever you push to your repository, a build and a deployment to your Cloud Run service is automatically invoked.

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.

Using minimal IAM permissions

When a container is deployed to a Cloud Run (fully managed) service, it runs with the identity of the Runtime Service Account of this Cloud Run (fully managed) service. Because Cloud Build can deploy new containers automatically, Cloud Build needs to be able to act as the Runtime Service Account of your Cloud Run (fully managed) service.

To grant limited access to Cloud Build to deploy to a Cloud Run (fully managed) service:

Console

  1. Go to the Service accounts page of the Google Cloud Console:

    Go to Service accounts

  2. Select the Runtime Service Account of your Cloud Run (fully managed) service (By default it is PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  3. Click Show Info Panel in the top right corner to show the Permissions tab.

  4. Click the Add member button.

  5. Enter the Cloud Build Service Account (PROJECT_NUMBER@cloudbuild.gserviceaccount.com)

  6. In the Select a role dropdown, select the Service Accounts > Service Account User role.

  7. Click Save.

gcloud

Use the gcloud iam service-accounts add-iam-policy-binding command, where PROJECT_NUMBER is the numeric ID of your project:

gcloud iam service-accounts add-iam-policy-binding \
  PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --member="serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

Replace PROJECT_NUMBER with the numeric ID of your project.

If using Cloud Run (fully managed) using a customized service identity, replace PROJECT_NUMBER-compute@developer.gserviceaccount.com with your service account address.

See Deployment permissions for more information.

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