Set descriptions (services)

This page shows how to set a custom description on your Cloud Run services. A description is an optional human-readable text attached to the service. A description is limited to 512 characters. If present, the description is displayed when viewing details of a service using gcloud run services describe.

Required roles

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

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.

Set or modify a description

You can set a description on Cloud Run services.


You can set or update the description during deployment:

gcloud run deploy SERVICE --description DESCRIPTION


  • SERVICE with name of your Cloud Run service
  • DESCRIPTION with the description of the service


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

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the annotation:

    kind: Service
      name: SERVICE
      annotations: "DESCRIPTION"


    • SERVICE with the name of your Cloud Run service
    • DESCRIPTION with the description of the service
  3. Create or update the service using the following command:

    gcloud run services replace service.yaml


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

The following google_cloud_run_v2_service resource specifies a description. Replace the description with your desired value.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-description"
  location = "us-central1"

  description = "This service has a custom description"

  template {
    containers {
      image = ""