Deploying container images

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

Permissions required to deploy

Permission requirements vary by the Cloud Run platform.

Deploying to Cloud Run (fully managed)

You must have ONE of the following roles:

Deploying to Cloud Run for Anthos on Google Cloud

You need permissions to create, update, and delete on the apiGroup serving.knative.dev and kind Service, and in addition you must have ONE of the following roles:

  • Owner
  • Editor
  • GKE Admin
  • GKE Developer

Images you can deploy

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

Images deployed to Cloud Run (fully managed)

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

Images deployed to Cloud Run for Anthos

You can use containers from any container registry, such as Docker Hub. For information on deploying private images from registries different from Container Registry or Artifact Registry, see Deploying private container images from other container registries.

Deploying a new service

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 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.

    create-service-image

    In the form,

    1. Select the Cloud Run platform you are deploying to:

      • Cloud Run (fully managed) to deploy to a fully managed environment.
      • Cloud Run for Anthos on Google Cloud to deploy to to a GKE or GKE on-prem cluster with Cloud Run for Anthos on Google Cloud enabled.
    2. If deploying to Cloud Run (fully managed):

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

      2. 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).

      3. 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.
    3. If deploying to Cloud Run for Anthos:

      1. From the dropdown menu, select one of the available GKE clusters for your service.

      2. Enter the desired service name. Service names must be unique per region and project or per cluster. A service name cannot be changed later.

      3. Under Connectivity:

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

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

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

      image

      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:

      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 gcr.io/PROJECT-ID/IMAGE

    • 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 PROJECT-ID with the Google Cloud project ID.
    • Replace IMAGE with the name of your image, for example, gcr.io/cloudrun/hello.

      If you deploy to Cloud Run (fully managed), and 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.

      If you deploy to Cloud Run for Anthos on Google Cloud, 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 for Anthos on Google Cloud, 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 run deploy SERVICE --platform managed --region REGION
  • For Cloud Run for Anthos on Google Cloud:
    gcloud run deploy SERVICE --platform gke --cluster CLUSTER-NAME --cluster-location CLUSTER-LOCATION
  • For Cloud Run for Anthos on-prem:
    gcloud run deploy SERVICE --platform kubernetes --kubeconfig KUBECONFIG-FILE

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-southeast1 (Singapore)
  • australia-southeast1 (Sydney)
  • northamerica-northeast1 (Montreal)

Note that it is not possible to use the domain mapping feature of Cloud Run (fully managed) for services in asia-northeast2, australia-southeast1 or northamerica-northeast1. You can use Cloud Load Balancing with a serverless NEG to map a custom domain to Cloud Run (fully managed) services in these regions.

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

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:

    image

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

  5. Optionally, set:

  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 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 Google Cloud project ID.
    • Replace and IMAGE with the name of your image, for example, gcr.io/cloudrun/hello.

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

      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

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.

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-southeast1 (Singapore)
  • australia-southeast1 (Sydney)
  • northamerica-northeast1 (Montreal)

Note that it is not possible to use the domain mapping feature of Cloud Run (fully managed) for services in asia-northeast2, australia-southeast1 or northamerica-northeast1. You can use Cloud Load Balancing with a serverless NEG to map a custom domain to Cloud Run (fully managed) services in these regions.

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

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. If you deploy to:

  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.

Deploying private container images from other container registries (Anthos)

This section describes setting up correct permissions to deploy container images from an arbitrary private registry to Cloud Run for Anthos. A private container registry requires credentials to access the container image. Note that you do not need to follow these steps to deploy private container images from Container Registry or Artifact Registry in the same project as your cluster.

To be able to deploy a private container image, you must create an imagePullSecret type Kubernetes secret and associate it with a service account:

  1. Create an imagePullSecret secret called container-registry:

    kubectl create secret container-registry \
    --docker-server=DOCKER_REGISTRY_SERVER \
    --docker-email=REGISTRY_EMAIL \
    --docker-username=REGISTRY_USER \
    --docker-password=REGISTRY_PASSWORD
    • Replace DOCKER_REGISTRY_SERVER with your private registry FQDN (ex: https://gcr.io/ for Container Registry or https://index.docker.io/v1/ for DockerHub).
    • Replace REGISTRY_EMAIL with your email.
    • Replace REGISTRY_USER with your container registry username.

      If you're using Container Registry or Artifact Registry and would like to store and pull long-lived credentials instead of passing short-lived access tokens, see Authentication methods: JSON key file.

    • Replace REGISTRY_PASSWORD with your container registry password.

  2. Open your default service account:

    kubectl edit serviceaccount default --namespace default

    Every namespace in your Kubernetes cluster has a default service account called default. This default service account is used to pull your container image unless otherwise specified in your Cloud Run for Anthos service's Revision Spec.

  3. Add the newly created imagePullSecret secret to your default service account:

    imagePullSecrets:
    - name: container-registry
    

    Your service account should now look like this:

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: default
      namespace: default
      ...
    secrets:
    - name: default-token-zd84v
    # The secret we just created:
    imagePullSecrets:
    - name: container-registry
    

Now, any new pods created in the current default namespace will have the imagePullSecret secret defined.

Deploying with automatic Istio sidecar injection enabled (Anthos)

To deploy your service on the namespace with automatic Istio sidecar injection enabled, you must use a separate Istio installation.

Deploying services on an internal network (Anthos)

Deploying services on an internal network is useful for enterprises that provide internal apps to their staff, and for services that are used by clients that run outside the Cloud Run for Anthos on Google Cloud cluster.

To deploy services on an internal network, see Setting up a private, internal network.

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: