Deploying container images

This page describes how to deploy new services and new revisions to Cloud Run (fully managed).

Permissions required to deploy

You must have ONE of the following roles:

• Owner
• Editor
• Both the Cloud Run Admin and Service Account User roles,
• Any custom role that includes this specific list of permissions.

Images you can deploy

There is no size limit that applies to the container image you can deploy.

You can deploy container images stored in Container Registry or Artifact Registry. You can use only the following types of container images:

• Container images stored in the same project as the one you want to deploy to.
• Container images from other Google Cloud projects (provided that the correct IAM permissions are set).
• Public container images from Container Registry or Artifact Registry.

Deploying a new service

You can specify a container image with a tag (for example, gcr.io/my-project/my-image:latest) or with an exact digest (for example, gcr.io/my-project/my-image@sha256:41f34ab970ee...).

Deploying to a service for the first time creates its first revision. Note that revisions are immutable. If you deploy from a container image tag, it will be resolved to a digest and the revision will always serve this particular digest.

You can deploy a container using the Cloud Console, the gcloud command line or from a YAML configuration file.

Click the tab for instructions using the tool of your choice.

Console

To deploy a container image:

1. Go to Cloud Run

2. Click Create service to display the Create service page.

   

   In the form,

   1. Select Cloud Run (fully managed) to deploy to a fully managed environment.

   2. Select the region where you want your service located.

   3. Enter the desired service name. Service names must be unique per region and project or per cluster. A service name cannot be changed later and is publicly visible when using Cloud Run (fully managed).

   4. Under Authentication,

      • If you are creating a public API or website, select Allow unauthenticated invocations. Selecting this assigns the IAM Invoker role to the special identifier allUser. You can use IAM to edit this setting later after you create the service.
      • If you want a secure service protected by authentication, select Require authentication.

   5. Click Next to continue to the second page of the service creation form:

      

      In the form,

      1. In the Container image URL textbox, supply the URL of an image from a supported registry, for example: gcr.io/cloudrun/hello

      2. Optionally, click Show Advanced Settings and the subsequent tabs to set:

         • Container configuration
         • Concurrency
         • Request timeout.
         • CPU allocation.
         • Memory limits
         • Maximum instances
         • Environment variables,
         • Cloud SQL connections, if you are deploying to Cloud Run (fully managed).

      3. Click Create to deploy the image to Cloud Run and wait for the deployment to finish.

3. Click the displayed URL link to open the unique and stable endpoint of your deployed service.

Command line

To deploy a container image:

1. Run the command:

   gcloud run deploy SERVICE --image IMAGE_URL

   • Replace SERVICE with the name of the service you want to deploy to. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.

   • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.

     If you are creating a public API or website, you can allow unauthenticated invocations of your service using the --allow-unauthenticated flag. This assigns the Cloud Run Invoker IAM role to allUsers. You can also specify --no-allow-unauthenticated to not allow unauthenticated invocations. If you omit either of these flags, you are prompted to confirm when the deploy command runs.

2. Wait for the deployment to finish. Upon successful completion, a success message is displayed along with the URL of the deployed service.

Note that to deploy to a different location from the one you set via the run/region gcloud properties, use:

• gcloud run deploy SERVICE --platform managed --region REGION

YAML

You can store your service specification in a YAML file and then deploy it using the gcloud command line.

1. Create a new service.yaml file with this content:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         containers:
         - image: IMAGE

   Replace

   • SERVICE with the name of your Cloud Run service
   • IMAGE with the URL of your container image.

   You can also specify more configuration such as environment variables or memory limits.

2. Deploy the new service using the following command:

   gcloud beta run services replace service.yaml

3. Optionally, make your service public if you want to allow unauthenticated access to the service.

Cloud Code

To deploy with Cloud Code, read the IntelliJ and Visual Studio Code guides.

Terraform

If you use Terraform, you can define your service in a Terraform configuration, using the google_cloud_run_service resource from the Google Cloud Platform Provider.

1. Create a new main.tf file with this content:

   provider "google" {
       project = "PROJECT-ID"
   }
   
   resource "google_cloud_run_service" "default" {
       name     = "SERVICE"
       location = "REGION"
   
       metadata {
         annotations = {
           "run.googleapis.com/client-name" = "terraform"
         }
       }
   
       template {
         spec {
           containers {
             image = "gcr.io/PROJECT-ID/IMAGE"
           }
         }
       }
    }
   
    data "google_iam_policy" "noauth" {
      binding {
        role = "roles/run.invoker"
        members = ["allUsers"]
      }
    }
   
    resource "google_cloud_run_service_iam_policy" "noauth" {
      location    = google_cloud_run_service.default.location
      project     = google_cloud_run_service.default.project
      service     = google_cloud_run_service.default.name
   
      policy_data = data.google_iam_policy.noauth.policy_data
   }
   

   Replace

   • PROJECT-ID with the Google Cloud project ID
   • REGION with the Google Cloud region
   • SERVICE with the name of your Cloud Run service
   • IMAGE with the name of your container image.

   The above configuration allows public access (the equivalent of --allow-unauthenticated). To make the service private, remove the google_iam_policy and google_cloud_run_service_iam_policy stanzas.

2. Initialize Terraform:

   terraform init

3. Apply the Terraform configuration:

   terraform apply

   Confirm you want to apply the actions described by entering yes.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• europe-north1 (Finland)
• europe-west1 (Belgium)
• europe-west4 (Netherlands)
• us-central1 (Iowa)
• us-east1 (South Carolina)
• us-east4 (Northern Virginia)
• us-west1 (Oregon)

Subject to Tier 2 pricing

• asia-east2 (Hong Kong)
• asia-northeast3 (Seoul, South Korea)
• asia-southeast1 (Singapore)
• asia-southeast2 (Jakarta)
• asia-south1 (Mumbai, India)
• australia-southeast1 (Sydney)
• europe-west2 (London, UK)
• europe-west3 (Frankfurt, Germany)
• europe-west6 (Zurich, Switzerland)
• northamerica-northeast1 (Montreal)
• southamerica-east1 (Sao Paulo, Brazil)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Cloud Console.

OK

Each service has a unique and permanent URL that will not change over time as you deploy new revisions to it.

Deploying a new revision of an existing service

You can deploy a new revision using the Cloud Console, the gcloud command line, or a YAML configuration file.

Note that changing any configuration settings results in the creation of a new revision, even if there is no change to the container image. Each revision created is immutable.

Click the tab for instructions using the tool of your choice.

Console

To deploy a new revision of an existing service:

1. Go to Cloud Run

2. Locate the service you want to update in the services list, and click on it to open the details of that service.

3. Click EDIT & DEPLOY NEW REVISION. This displays the revision deployment form:

   

4. If needed, supply the URL to the new container image you want to deploy.

5. Optionally, set:

   • Container configuration
   • Concurrency
   • Request timeout.
   • CPU allocation.
   • Memory limits
   • Maximum instances
   • Environment variables,
   • Cloud SQL connections, if you are deploying to Cloud Run (fully managed).

6. To send all traffic to the new revision, check the checkbox labelled Serve this revision immediately. To gradually roll out a new revision, uncheck that checkbox: this will result in a deployment where no traffic is sent to the new revision--follow the instructions for gradual rollouts after you deploy.

7. Click DEPLOY and wait for the deployment to finish.

Command line

To use the command line, you need to have already set up the gcloud command line.

To deploy a container image:

1. Run the command:

   gcloud run deploy SERVICE --image IMAGE_URL

   • Replace SERVICE with the name of the service you are deploying to. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.

   • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.

     The revision suffix is assigned automatically for new revisions. If you want to supply your own revision suffix, use the gcloud command line parameter --revision-suffix.

2. Wait for the deployment to finish. Upon successful completion, a success message is displayed along with the URL of the deployed service.

YAML

Caution: The following instructions replaces your existing service configuration with the one specified in the YAML file. So if you use YAML to make revision changes, you should avoid also using the Cloud Console or gcloud command line to make configuration changes because those can be overwritten when you use YAML.

If you need to download or view the configuration of an existing service, use the following command to save results to a YAML file:

gcloud run services describe SERVICE --format export > service.yaml

From a service configuration YAML file, modify any spec.template child attributes as desired to update revision settings, then deploy the new revision:

gcloud beta run services replace service.yaml

Cloud Code

To deploy a new revision of an existing service with Cloud Code, read the IntelliJ and Visual Studio Code guides.

Terraform

You will already need to have setup Terraform as per the Deploying a new service example.

1. Make a change to the configuration file.

2. Apply the Terraform configuration:

   terraform apply

   Confirm you want to apply the actions described by entering yes.

   Note: unless a configuration change is required, no new revision will be created.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• europe-north1 (Finland)
• europe-west1 (Belgium)
• europe-west4 (Netherlands)
• us-central1 (Iowa)
• us-east1 (South Carolina)
• us-east4 (Northern Virginia)
• us-west1 (Oregon)

Subject to Tier 2 pricing

• asia-east2 (Hong Kong)
• asia-northeast3 (Seoul, South Korea)
• asia-southeast1 (Singapore)
• asia-southeast2 (Jakarta)
• asia-south1 (Mumbai, India)
• australia-southeast1 (Sydney)
• europe-west2 (London, UK)
• europe-west3 (Frankfurt, Germany)
• europe-west6 (Zurich, Switzerland)
• northamerica-northeast1 (Montreal)
• southamerica-east1 (Sao Paulo, Brazil)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Cloud Console.

OK

Deploying images from other Google Cloud projects

You can deploy container images from other Google Cloud projects if you set the correct IAM permissions:

1. In the Cloud Console console, open the project for your Cloud Run service.

2. Go to the IAM page

3. Copy the email of the Cloud Run service agent. It has the suffix @serverless-robot-prod.iam.gserviceaccount.com

4. Open the project that owns the container registry you want to use.

5. Go to the IAM page

6. Click Add to add a new member.

7. In the New members text box, paste in the email of the service account that you copied earlier.

8. In the Select a role dropdown list, select the role Storage -> Storage Object Viewer.

9. Deploy the container image to the project that contains your Cloud Run service.

   Note: For stronger security, limit grant access to only the Cloud Storage bucket that contains your container images.

What's next

After you deploy a new service, you can do the following:

• Gradual rollouts, rollback revisions, traffic migration
• View service logs
• Monitor service performances
• Set memory limits
• Set environment variables
• Change service concurrency
• Manage the service
• Manage service revisions

You can automate the builds and deployments of your Cloud Run services using Cloud Build Triggers:

• Set up Continuous Deployment