Deploying container images

This page describes how to deploy new services and new revisions to Cloud Run or Cloud Run on GKE.

Permissions required to deploy

In order to deploy to Cloud Run, you must have the Owner or Editor role, or you must have the Cloud Run Admin role and have performed the additional configuration.

In order to deploy a service to Cloud Run on GKE, you must have the Owner, Editor, GKE Admin, or GKE Developer role.

Images you can deploy

For Cloud Run, you can deploy container images stored in Container Registry. You can use only the following types of container images:

For Cloud Run on GKE, you can use containers from any container registry, for example Docker Hub, so long as the container image is public.

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

Deploying a new service

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 GCP Console or the gcloud command line. 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.

    image

    In the form,

    1. Supply the URL of an image in Container Registry, for example, gcr.io/cloudrun/hello

    2. Specify a lowercase, alphanumeric name for your service.

    3. In the Location dropdown, select the location where you want your service located.

      • For Cloud Run, select the desired region for the service.
      • For Cloud Run on GKE, select the cluster and cluster location for your service.
    4. If deploying to Cloud Run, not to Cloud Run on GKE, select the checkbox Allow unauthenticated invocations under Authentication if you are creating a public API or website. Otherwise, leave it unselected. 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.

    5. If you are creating a service for Cloud Run on GKE, under Connectivity,

      • Select External to allow external access to your service
      • Select Internal if you want to restrict access only to other Cloud Run on GKE services or services in your cluster that use istio.

      Note that you can change the connectivity option at any time, as described in Changing service connectivity settings.

    6. Optionally, set environment variables, concurrency, and memory limits.

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

  4. 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 beta run deploy [SERVICE] --image gcr.io/[PROJECT-ID]/[IMAGE]
    
    • 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 [PROJECT-ID] with the GCP project ID.
    • Replace [IMAGE] with the name of your image, for example, gcr.io/cloudrun/hello.

      If you deploy to Cloud Run, and you are creating a public API or website, you can allow unauthenticated invocations to 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.

      If you deploy to Cloud Run on GKE, you can set connectivity options with the --connectivity flag as described in Changing service connectivity settings to specify internal or external access.

      If you deploy to Cloud Run on GKE, and you are using a namespace other than the default, you must also specify that namespace using the --namespace parameter.

  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 or run/cluster and run/cluster_location gcloud properties, use:

  • For Cloud Run: gcloud beta run deploy [SERVICE] --platform managed --region [REGION],
  • For Cloud Run on GKE: gcloud beta run deploy [SERVICE] --platform gke --cluster [CLUSTER-NAME] --cluster-location [CLUSTER-LOCATION]

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 GCP products that are used by your Cloud Run service. Using GCP products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

  • us-central1 (Iowa)

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

Deploying a new revision of an existing service

You can deploy a new revision using the GCP Console or the gcloud command line.

Note that changing the memory limit, environment variables, or concurrency also results in the creation of a 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 DEPLOY NEW REVISION. This displays the revision deployment form:

    image

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

  5. If needed, set environment variables, concurrency, and memory limits.

  6. Click DEPLOY and wait for the deployment to finish. When deployment is complete, all traffic to the service is handled by the new revision.

Command line

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

To deploy a container image:

  1. Run the command:

    gcloud beta run deploy [SERVICE] --image gcr.io/[PROJECT-ID]/[IMAGE]
    
    • 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 [PROJECT-ID] with the GCP project ID.
    • Replace and [IMAGE] with the name of your image, for example, gcr.io/cloudrun/hello.

      If deploying to Cloud Run on GKE, if you are using a namespace other than the default, you must also specify that namespace using the --namespace parameter.

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

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 GCP products that are used by your Cloud Run service. Using GCP products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

  • us-central1 (Iowa)

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

Deploying images from other GCP projects

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

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

  2. Go to the IAM page

  3. If you deploy to:

    • Cloud Run, copy the email of the Cloud Run service agent. It has the suffix @serverless-robot-prod.iam.gserviceaccount.com

    • Cloud Run on GKE, copy the email of the Compute Engine default service account. It has the suffix @developer.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.

What's next

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

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

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Run Documentation