Create and manage Cloud Run instances

Preview — Cloud Run instances

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to create and manage individually addressable, singleton Cloud Run instances. Unlike Cloud Run services that scale based on incoming traffic, an instance is a dedicated compute container that you manage manually using lifecycle transitions (create, stop, start, update, delete).

Before you begin

1. Set up a new project for Cloud Run, as described in the setup page.

2. Enable the Cloud Run Admin API:

   gcloud services enable run.googleapis.com
   

3. Update gcloud components to the latest version:

   gcloud components update

4. If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

Required roles

To get the permissions that you need to configure and deploy Cloud Run instances, ask your administrator to grant you the following IAM roles:

• Cloud Run Developer (roles/run.developer) on the Cloud Run instance
• Service Account User (roles/iam.serviceAccountUser) on the service identity

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run instance interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Create an instance

You can deploy a container image to create a new instance. If you don't provide a name, one is automatically generated.

gcloud

To create a new Cloud Run instance using the gcloud beta run instances create command:

gcloud beta run instances create INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

To create a new Cloud Run instance using the gcloud beta run instances deploy command:

gcloud beta run instances deploy INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

Replace the following:

• INSTANCE_NAME: the name of the instance you are creating. The instance name must be unique within your project and region. You cannot create an instance with the same name as an existing Cloud Run instance or service.
• IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/instances:latest.
• REGION: the Google Cloud region where you are running your instance, for example europe-west1.

Client libraries

To create a new instance from code:

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

REST API

To create a new Cloud Run instance, send a POST HTTP request to the instances endpoint.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "containers": [{
      "image": "IMAGE_URL",
      "ports": [{"containerPort": PORT}]
    }],
    "ingress": "INGRESS_TRAFFIC_ALL",
    "invokerIamDisabled": true,
    "timeout": "3600s"
  }' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances?instance_id=INSTANCE_NAME"

Replace the following:

• IMAGE_URL: your container image URL.
• PORT: the port your container listens on.
• PROJECT_ID: your Google Cloud project ID.
• REGION: the Google Cloud region of your deployment.
• INSTANCE_NAME: the name of your new instance.

After you create an instance, the instance receives a Cloud Run URL that has the following format:

https://INSTANCE_NAME-PROJECT_NUMBER.REGION.run.app

Update an instance

When you update an instance, such as its container image, port, or environment variables, the instance is restarted.

Caution: Cloud Run instances don't have persistent disk storage. If you need to preserve your files and data, save them to an external storage before updating.

gcloud

To update a Cloud Run instance using the gcloud beta run instances update command:

gcloud beta run instances update INSTANCE_NAME \
    --image NEW_IMAGE_URL \
    --region REGION

To update a Cloud Run instance using the gcloud beta run instances deploy command:

gcloud beta run instances deploy INSTANCE_NAME \
    --image IMAGE_URL \
    --region REGION

REST API

To update a Cloud Run instance config from the API, send a PATCH HTTP request to the instance URI endpoint.

curl -H "Content-Type: application/json" \
  -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

Stop an instance

Use the stop command or method to stop a running Cloud Run instance.

Caution: Stopping an instance terminates the active container runtime, deleting all in-memory files and unpersisted system state. If you need to preserve your files and data, save them to an external storage before stopping.

gcloud

To stop an instance:

gcloud beta run instances stop INSTANCE_NAME \
    --region REGION

Client libraries

To stop a running instance from code:

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

REST API

To stop an instance, send a POST HTTP request with the :stop decorator:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME:stop"

Start or restart an instance

Use the start command or method to start up a stopped instance, or force a restart on an existing instance.

gcloud

To start or restart an instance:

gcloud beta run instances start INSTANCE_NAME \
    --region REGION

Client libraries

To start a stopped instance from code:

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

REST API

To start an instance, send a POST HTTP request with the :start decorator:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME:start"

View the list of instances in your project

You can view all active and inactive instances in your project.

gcloud

To list the instances in a specific region:

gcloud beta run instances list \
    --region REGION

Replace REGION with the Google Cloud region where you are running your instance.

Client libraries

To list active and inactive instances from code:

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

REST API

To retrieve a list of instances, send a GET HTTP request:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances"

View instance details

Use the describe command or method to view configuration details and current status.

gcloud

To describe an instance:

gcloud beta run instances describe INSTANCE_NAME \
    --region REGION

Client libraries

To view instance configuration details and status from code:

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

REST API

To describe an instance, send a GET HTTP request:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

Delete an instance

Delete an instance to permanently remove its configuration, metadata, public direct URL mapping, and identity roles from your project.

Caution: After deletion, the instance is removed forever and cannot be started or recovered.

gcloud

To delete an instance:

gcloud beta run instances delete INSTANCE_NAME \
    --region REGION

Client libraries

To delete an instance from code:

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

REST API

To delete an instance, send a DELETE HTTP request:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_NAME"

What's next

• To view the logging transactions for your instances, see Logging and viewing logs in Cloud Run.
• Configure your Cloud Run instance:
  • Memory limits
  • CPU limits
  • Container port and entrypoint
  • Environment variables
  • Volume mounts
  • Container health check
  • Secrets
  • Service identity
  • Default URL
  • Restart policy
  • IAP