Deploying container images to Cloud Run

Console

To deploy a container image:

1. In the Google Cloud console, go to the Cloud Run page:

   Go to Cloud Run

2. Click Deploy container and select Service to display the Create service form.

   1. In the form, select the deployment option:

      1. If you want to manually deploy a container, select Deploy one revision from an existing container image and specify the container image.

      2. If you want to automate for continuous deployment, select Continuously deploy new revisions from a source repository and follow the instructions for continuous deployments.

   2. Enter the needed service name. Service names must be 49 characters or less and must be unique per region and project. A service name cannot be changed later and is publicly visible.

   3. Select the region where you want your service located. The region selector indicates price tier, availability of domain mappings and highlights regions with the lowest carbon impact.

   4. Set CPU allocation and pricing as needed.

   5. Under Autoscaling, specify minimum and maximum instances.

   6. Set the Ingress settings in the form as needed.

   7. Under Authentication, configure the following:

      • 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. Click Container(s), volumes, networking, security to set other optional settings in the appropriate tabs:

   • Concurrency
   • Container configuration
   • CPU limits
   • Memory limits
   • Request timeout
   • Secrets
   • Environment variables
   • Execution environment
   • HTTP/2
   • Service accounts
   • Cloud SQL connections
   • VPC connection

4. When you are finished configuring your service, click Create to deploy the image to Cloud Run and wait for the deployment to finish.

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. To deploy a container image:

   1. Run the following command:

      gcloud run deploy SERVICE --image IMAGE_URL

      • Replace SERVICE with the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project. 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, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG . Note that if you don't supply the --image flag, the deploy command will attempt to deploy from source code.

      If you are creating a public API or website, 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 disallow 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 using the run/region gcloud properties, use:

   gcloud run deploy SERVICE --region REGION

YAML

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

1. Create a new service.yaml file with the following 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. Service names must be 49 characters or less and must be unique per region and project.
   • 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 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, define your service in a Terraform configuration, using the google_cloud_run_v2_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_v2_service" "default" {
     name     = "SERVICE"
     location = "REGION"
     client   = "terraform"
   
     template {
       containers {
         image = "IMAGE"
       }
     }
   }
   
   resource "google_cloud_run_v2_service_iam_member" "noauth" {
     location = google_cloud_run_v2_service.default.location
     name     = google_cloud_run_v2_service.default.name
     role     = "roles/run.invoker"
     member   = "allUsers"
   }
   

   Replace

   • PROJECT-ID with the Google Cloud project ID
   • REGION with the Google Cloud region
   • SERVICE with the name of your Cloud Run service. Service names must be 49 characters or less and must be unique per region and project.
   • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

   This configuration allows public access (the equivalent of --allow-unauthenticated). To make the service private, remove the google_cloud_run_v2_service_iam_member stanza.

2. Initialize Terraform:

   terraform init

3. Apply the Terraform configuration:

   terraform apply

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

Client libraries

To deploy a new service from code:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

REST API

To deploy a new service, send a POST HTTP request to the Cloud Run Admin API service endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services?serviceId=SERVICE

Replace:

• ACCESS_TOKEN with a valid access token for an account that has the IAM permissions to deploy services. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
• IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
• SERVICE with the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project.
• REGION with the Google Cloud region of the service.
• PROJECT-ID with the Google Cloud project ID.

Console

To deploy a new revision of an existing service:

1. In the Google Cloud console, go to the Cloud Run page:

   Go to Cloud Run

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

3. Click Edit and deploy new revision to display the revision deployment form.

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

   2. Configure the container as needed.

   3. Set CPU allocation and pricing as needed.

   4. Under Capacity, specify memory limits. and CPU limits.

   5. Specify request timeout and concurrency as needed.

   6. Specify execution environment as needed.

   7. Under Autoscaling, specify minimum and maximum instances.

   8. Use the other tabs as needed to optionally configure:

      • Secrets
      • Environment variables
      • HTTP/2
      • Service accounts
      • Cloud SQL connections
      • VPC connection

4. To send all traffic to the new revision, select Serve this revision immediately. To gradually roll out a new revision, clear that checkbox. This results in a deployment where no traffic is sent to the new revision. Follow the instructions for gradual rollouts after you deploy.

5. Click Deploy and wait for the deployment to finish.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 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, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

      The revision suffix is assigned automatically for new revisions. If you want to supply your own revision suffix, use the gcloud CLI 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 needed to update revision settings, then deploy the new revision:

gcloud 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

Make sure you have setup Terraform as described in 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.

Client libraries

To deploy a new revision from code:

• Go
• Java
• Node.js
• Python
• Ruby
• PHP
• .NET

REST API

To deploy a new revision, send a PATCH HTTP request to the Cloud Run Admin API service endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X PATCH \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE

Replace:

• ACCESS_TOKEN with a valid access token for an account that has the IAM permissions to deploy revisions. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
• IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
• SERVICE with the name of the service you are deploying to.
• REGION with the Google Cloud region of the service.
• PROJECT-ID with the Google Cloud project ID.

Console

1. In the Google Cloud console, go to the Cloud Run page:

   Go to Cloud Run

   • To deploy to an existing service, locate it in the services list, and click to open, then click EDIT & DEPLOY NEW REVISION to display the revision deployment form.
   • Click Deploy container and select Service to display the Create service form.

2. For a new service,

   1. Supply the service name and the URL to the ingress container image you want to deploy.
   2. Click Container(s), volumes, networking, security

3. In the Edit container card, configure the ingress container as needed.

4. Click Add container and configure a sidecar container you want to add alongside the ingress container. If the sidecar depends on another container in the service, indicate this in the Container start-up order drop-down menu. Repeat this step for each sidecar container you are deploying.

5. To send all traffic to the new revision, select Serve this revision immediately. For a gradual rollout, clear that checkbox. This results in a deployment where no traffic is sent to the new revision. Follow the instructions for gradual rollouts after you deploy.

6. Click Create for a new service or Deploy for an existing service, then wait for the deployment to finish.

gcloud

The container parameters in Google Cloud CLI are in Preview.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. To deploy multiple containers to a service, run the following command:

   gcloud run deploy SERVICE \
    --container INGRESS_CONTAINER_NAME \
    --image='INGRESS_IMAGE' \
    --port='CONTAINER_PORT' \
    --container SIDECAR_CONTAINER_NAME \
    --image='SIDECAR_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.
   • INGRESS_CONTAINER_NAME with a name for the container receiving requests, for example app.
   • INGRESS_IMAGE with a reference to the container image that should receive requests, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.
   • CONTAINER_PORT with the port where the ingress container listens for incoming requests. Unlike a single-container service, for a service containing sidecars, there is no default port for the ingress container. You must explicitly configure the container port for the ingress container and only one container can have the port exposed.
   • SIDECAR_CONTAINER_NAME with a name for the sidecar container, for example sidecar.
   • SIDECAR_IMAGE with a reference to the sidecar container image

   If you want to configure each container in the deploy command, supply each container's configuration after the container parameters, for example:

   gcloud run deploy SERVICE \
     --container CONTAINER_1_NAME \
     --image='INGRESS_IMAGE' \
     --set-env-vars=KEY=VALUE \
     --port='CONTAINER_PORT' \
     --container SIDECAR_CONTAINER_NAME \
     --image='SIDECAR_IMAGE' \
     --set-env-vars=KEY_N=VALUE_N

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

YAML

These instructions show a basic YAML file for your Cloud Run service with sidecars. Create a file named service.yaml and add the following to it:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - image: INGRESS_IMAGE
        ports:
          - containerPort: CONTAINER_PORT
      - image: SIDECAR_IMAGE
      

Replace

• SERVICE with the name of your Cloud Run service. Service names must be 49 characters or less.
• CONTAINER_PORT with the port where the ingress container listens for incoming requests. Unlike a single-container service, for a service containing sidecars, there is no default port for the ingress container. You must explicitly configure the container port for the ingress container and only one container can have the port exposed.
• INGRESS_IMAGE with a reference to the container image that should receive requests, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.
• SIDECAR_IMAGE with a reference to the sidecar container image. You can specify multiple sidecars by adding more elements to the containers array in the YAML.

After you update the YAML to include the ingress and sidecar containers, deploy to Cloud Run using the command:

gcloud run services replace service.yaml

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Add the following to a google_cloud_run_v2_service resource in your Terraform configuration.

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"
  ingress = "INGRESS_TRAFFIC_ALL"
  template {
    containers {
      name = "INGRESS_CONTAINER_NAME"
      ports {
        container_port = CONTAINER_PORT
      }
      image = "INGRESS_IMAGE"
      depends_on = ["SIDECAR_CONTAINER_NAME"]
    }
    containers {
      name = "SIDECAR_CONTAINER_NAME"
      image = "SIDECAR_IMAGE"
      }
    }
  }

The CONTAINER_PORT represents the port where the ingress container listens for incoming requests. Unlike a single-container service, for a service containing sidecars, there is no default port for the ingress container. You must explicitly configure the container port for the ingress container and only one container can have the port exposed.