Managing Services

This page describes creating a service and viewing information about a service.

Each service has a unique and permanent run.app URL that won't change over time as you deploy new revisions to it. Functions deployed on Cloud Run are also treated as a service and assigned a run.app address. The service's permanent domain consists of the service name and a hash.

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.

Create a service

You create a new service by deploying a container image to it for the first time. Deploying a new service has more instructions.

View the list of services in your project

You can view a list of the available services in your project using Google Cloud console or the gcloud command line:

Console

To view the services list:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Examine the displayed list of services for your project:

gcloud

To list the services in your project:

gcloud run services list

Note that each service has an associated URL.

You can filter this list by properties of the service definition, such as an assigned label.

Cloud Code

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

Client libraries

To view the list of services from code:

REST API

To view the list of services in your project, send a GET 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 GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services

Replace:

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

View the list of functions in your project

You can view a list of the available functions in your project using the Google Cloud console:

Console

To filter for functions in your service list:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Examine the displayed list of services for your project:
Select Filter services > Deployment type > Function.

If you previously deployed your function using the Cloud Functions (2nd gen API), the Deployed by column will show Cloud Functions.

Copy a service

You can make a copy of an existing service using Google Cloud console or YAML. You can change anything you want in the copy, including name and region.

Console

To copy a service:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Select the service to copy from the displayed list of services for your project:
1. Click Copy.
2. In the service copy page, set or change any values you want to change, such as region, etc. If you are keeping the same region, you must provide a new name for the service.
3. Click Create to make a copy and deploy it using the new service name.

YAML

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
```
Make any desired configuration changes to the service.
```
 apiVersion: serving.knative.dev/v1
 kind: Service
 metadata:
   annotations:
     ...
   name: SERVICE
   ...
 spec:
   template:
     metadata:
       annotations:
       ...
       name: REVISION
```
- If you are not deploying the copy to a different region, replace SERVICE with the name you want to use for the copy. If you are deploying the copy to a different region, you can use the old name.
- Replace REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
  - Starts with SERVICE-
  - Contains only lowercase letters, numbers and -
  - Does not end with a -
  - Does not exceed 63 characters
Copy the service using the following command:
```
gcloud run services replace service.yaml
```
Use the --region flag to deploy the copy to a different region.

View more details about a service

To see more details about a service,

Console

To view a service's details:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Click on the desired service in the displayed list of services for your project to open the service details view.

gcloud

To view details about a service:

gcloud run services describe SERVICE

Replace SERVICE with the name of the service.

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

gcloud run services describe SERVICE --region REGION --format yaml

Replace:

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

You can use --format export to export as YAML without automatically generated labels or status:

gcloud run services describe SERVICE --region REGION --format export

You can also use the --format flag to get the URL of the service:

gcloud run services describe SERVICE --region REGION --format='value(status.url)'

Cloud Code

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

For more details on service revisions, see Managing Revisions.

Client libraries

To view details about a service from code:

REST API

To view details about a service, send a GET 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 GET \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-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.
REGION with the Google Cloud region of the service.
PROJECT-ID with the Google Cloud project ID.

Disable an existing service

To get the permissions that you need to disable an existing Cloud Run service and revision, ask your administrator to grant you the Cloud Run Admin (roles/run.admin) IAM role on your project.

Cloud Run does not offer a direct way to make a service stop serving traffic, but you can achieve a similar result by revoking the permission to invoke the service to identities that are invoking the service. Notably, if your service is "public", remove allUsers from the Cloud Run Invoker role (roles/run.invoker).

Delete existing services

The following considerations apply to deleting a service:

Deleting a service deletes all resources related to this service, including all revisions of this service whether they are serving traffic or not.
Deleting a service does not automatically remove container images from Container Registry. To delete container images used by the deleted revisions from Container Registry, refer to Deleting images.
Deleting a service with one or more Eventarc triggers does not automatically delete these triggers. To delete the triggers refer to Manage triggers.
After deletion, the service remains visible in the Google Cloud console and in the command line interface until the deletion is fully complete. However, you cannot update the service.
Deleting a service is permanent: there is no undo or restore. However, if after deleting a service, you deploy a new service with the same name in the same region, it will have the same endpoint URL.

Console

To delete a service:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Locate the service you want to delete in the services list, and click its checkbox to select it.
Click DELETE. This deletes all revisions of the service.

gcloud

To delete a service, use the command:

gcloud run services delete SERVICE --region REGION

Replace

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

Client libraries

To delete a service from code:

REST API

To delete a service, send a DELETE 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 DELETE \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE-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.
REGION with the Google Cloud region of the service.
PROJECT-ID with the Google Cloud project ID.