Configure restart policy for 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.

The Cloud Run instance's restart policy determines if and when the instance should restart.

Restart policy options

Select from the following restart policies:

• on-failure (default): If any container exits with a non-zero status code, or if the container experiences infrastructure failures, the instance restarts. For multi-container instances this means any container failing causes the entire instance to restart.
• always: When any container exits, the instance always restarts. This includes clean exits with code 0.
• never: The instance never restarts. When any container terminates, the instance transitions immediately to a STOPPED or FAILED state.

When you configure the always or on-failure restart policy for your instance, your instance automatically restarts at the end of an approximately 7-day lifecycle, therefore running indefinitely unless it's interrupted otherwise.

Note: When a multi-container Cloud Run instance has its restart policy set to always and any container exits with code 0, Cloud Run stops the instance instead of restarting it.

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.

Configure restart policy

Configure the restart policy for a Cloud Run instance using the Google Cloud CLI or YAML:

gcloud

To specify a restart policy when deploying a new instance:

gcloud beta run instances deploy INSTANCE \
    --image=IMAGE_URL \
    --restart-policy=POLICY

To update the restart policy of an existing instance:

gcloud beta run instances update INSTANCE \
    --restart-policy=POLICY

Replace the following:

• INSTANCE: the name of the instance.
• IMAGE_URL: a reference to the container image, such as us-docker.pkg.dev/cloudrun/container/hello:latest.
• POLICY: the restart policy to apply. Choose from on-failure, always, or never.

YAML

1. If you are creating a new instance, skip this step. If you are updating an existing instance, download its YAML configuration:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. The following example contains the YAML configuration:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - name: CONTAINER_NAME
       image: IMAGE_URL
     restartPolicy: POLICY

   Replace the following:

   • INSTANCE: the name of your Cloud Run instance.
   • CONTAINER_NAME: the name of the container.
   • IMAGE_URL: a reference to the container image, such as us-docker.pkg.dev/cloudrun/container/hello:latest.
   • POLICY: the restart policy to apply. Choose from on-failure, always, or never.

3. Create or update the instance using the following command:

   gcloud beta run instances replace instance.yaml