Manage revisions

When you deploy to a service or change the configuration of a service, an immutable revision is created.

The following considerations apply to revisions:

  • You can specify whether a new revision receives all, none, or some of the traffic, you can gradually roll out a new revision, you can split traffic between several revisions, and you can roll back from a revision. For more information, refer to Rollbacks, gradual rollouts, and traffic migration.
  • You can optionally use revision tags to test a revision that is not serving traffic.
  • You don't need to manually delete revisions, although you can if you want.
  • Non-serving revisions do not consume any resources and are not billed.
  • There is a maximum of 1000 revisions per service: If you exceed that limit, older revisions are automatically deleted.
  • The revision suffix is assigned automatically. If you want to use your own version suffix, you can do so using the gcloud CLI parameter --revision-suffix.

Required roles

To get the permissions that you need to manage Cloud Run services and revisions, ask your administrator to grant you the Cloud Run Developer (roles/run.developer) IAM role on your Cloud Run service.

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

View the list of revisions for a service

Console

To view the list of revisions in your project:

  1. Go to Cloud Run

  2. Locate the service in the services list, and click on it.

  3. Click the Revisions tab to show the list of current revisions for that service.

    revision list

gcloud

To view the list of revisions for a given service:

  1. Find your service name from the list of services available in your project:

    gcloud run services list

  2. Use the following command to get all the revisions for the service you just looked up:

    gcloud run revisions list --service SERVICE --region REGION

    Replace

    • SERVICE with the name of your service.
    • REGION with the Google Cloud region of the service.

Cloud Code

To view the list of revisions with Cloud Code, read the Cloud Run Explorer guides for IntelliJ and Visual Studio Code.

Client libraries

To view the list of revisions from code:

REST API

To view the list of revisions, send a GET HTTP request to the Cloud Run Admin API revisions endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-NAME/revisions

Replace:

  • ACCESS_TOKEN with a valid access token for an account that has the IAM permissions to view 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.
  • SERVICE-NAME with the name of the service.
  • REGION with the Google Cloud region of the service.
  • PROJECT-ID with the Google Cloud project ID.

View revision details

Console

To view the details for a revision in your project:

  1. Go to Cloud Run

  2. Select your service in the services list.

  3. Click the Revisions tab to show the list of current revisions for that service.

  4. Select the service revision you are interested in:

  5. Examine the DETAILS panel at the far right for revision-specific information such as the URL of the deployed container image, amount of memory allocated, environment variables, and possibly build and source repository information.

    image

gcloud

To view the details for a revision in your project:

  1. Find your service name from the list of services available in your project:

    gcloud run services list

  2. Use the following command to get all the revisions for the service you just looked up: 

    gcloud run revisions list --service SERVICE --region REGION

    Replace

    • SERVICE with the name of your service.
    • REGION with the Google Cloud region of the service.

  3. Use the following command to see more details about a specific revision: 

    gcloud run revisions describe REVISION --region REGION
    Replace

    • REVISION with the name of the revision you want to learn more about.
    • REGION with the Google Cloud region of the service.

    You can use the --format flag to format the output. For example as YAML: 

    gcloud run revisions describe REVISION --region REGION --format yaml

Cloud Code

To view the details of a revision with Cloud Code, read the Cloud Run Explorer guides for IntelliJ and Visual Studio Code.

Client libraries

To view the details of a revision from code:

REST API

To view details about a revision, send a GET HTTP request to the Cloud Run Admin API revisions endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-NAME/revisions/REVISION-NAME

Replace:

  • ACCESS_TOKEN with a valid access token for an account that has the IAM permissions to view service details. 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.
  • SERVICE-NAME with the name of the service.
  • REVISION-NAME with the name of the revision.
  • REGION with the Google Cloud region of the service.
  • PROJECT-ID with the Google Cloud project ID.

Note that a non-current revision may have the status of RETIRED, which means that Cloud Run has retired the infrastructure needed for that particular revision.

About build and source repository information in the Details panel

If the Artifact Analysis API is enabled and the container was built with Cloud Build, build information is displayed in the Details panel.

Additionally, if a Cloud Build trigger was used to build the container, source repository information is also displayed in the Details panel.

Delete revisions

A common use case for deleting a revision is when you want to make sure a particular revision won't be accidentally used.

You cannot delete a revision if:

  • it is able to receive traffic,
  • it is the only revision of the service,
  • it is the latest revision of the service.

When you delete a revision, the container image used by this revision is not deleted automatically from Container Registry or Artifact Registry. To delete a container image from a registry, see the deletion instructions for Container Registry or Artifact Registry.

You cannot undo a revision deletion.

You can use either the console or the command line:

Console

To delete a revision

  1. Go to Cloud Run

  2. Locate the service in the services list, and click on it.

  3. Click the Revisions tab to show the list of current revisions for that service.

  4. Locate the service revision you want to delete.

  5. Click the three-dot vertical ellipse to the left of the revision to show the Delete menu.

    revision-delete

  6. Click Delete to delete the revision.

gcloud

To delete a revision, use the following command:

gcloud run revisions delete REVISION --region REGION

Replace

  • REVISION with the name of the revision you want to delete.
  • REGION with the Google Cloud region of the service.

Client libraries

To delete a revision from code:

REST API

To delete a revision, send a DELETE HTTP request to the Cloud Run Admin API revisions endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X DELETE \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-NAME/revisions/REVISION-NAME

Replace:

  • ACCESS_TOKEN with a valid access token for an account that has the IAM permissions to delete a service. 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.
  • SERVICE-NAME with the name of the service.
  • REVISION-NAME with the name of the revision.
  • REGION with the Google Cloud region of the service.
  • PROJECT-ID with the Google Cloud project ID.

What's next

After you deploy a revision, you can do the following: