In this tutorial, you create an inventory of Cloud Run services
using the gcloud
and gsutil
command line tools inside a Cloud Run
service. You can apply what you learn in this tutorial to your existing Cloud
operations scripts or to build a proof-of-concept before using client libraries
to build a more robust service.
You use the gcloud
and gsutil
tools like any shell script inside a web
service, for example, as shown in the Shell quickstart.
On Cloud Run, both tools work with Google Cloud
services by automatically authenticating with the Cloud Run
service identity. Any permissions given
to the service identity are available to the gcloud CLI.
The gcloud CLI is so broadly capable of information gathering and resource management across Google Cloud that the challenge of using it within a web service is minimizing the risk of a caller misusing these capabilities. Without security controls, you could create risk to other services or resources running in the same project by allowing accidental or intentional malicious activity. Examples of these risks include:
- Enabling the discovery of IP addresses of private virtual machines
- Enabling access to private data from a database in the same project
- Enabling deletion of other running services
Several steps in this tutorial show how to impose controls to minimize risks,
such as specifying the gcloud
command to be run in the code, instead of leaving
it open as a user input.
Scripting with the command line tool inside a Cloud Run service is similar to using the command line locally. The main difference is the additional restrictions you should add around the primary script logic.
Objectives
- Write and build a custom container with a Dockerfile
- Write, build, and deploy a Cloud Run service
- Use the
gcloud
andgsutil
tools safely in a web service - Generate a report of Cloud Run services and save to Cloud Storage
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage,
use the pricing calculator.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.
-
Enable the Cloud Run, Cloud Build, and Cloud Storage APIs.
- Install and initialize the gcloud CLI.
Required roles
To get the permissions that you need to complete the tutorial, ask your administrator to grant you the following IAM roles on your project:
-
Cloud Build Editor (
roles/cloudbuild.builds.editor
) -
Cloud Run Admin (
roles/run.admin
) -
Create Service Accounts (
roles/iam.serviceAccountCreator
) -
Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) -
Service Account User (
roles/iam.serviceAccountUser
) -
Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer
) -
Storage Admin (
roles/storage.admin
)
For more information about granting roles, see Manage access.
You might also be able to get the required permissions through custom roles or other predefined roles.
Setting up gcloud defaults
To configure gcloud with defaults for your Cloud Run service:
Set your default project:
gcloud config set project PROJECT_ID
Replace PROJECT_ID with the name of the project you created for this tutorial.
Configure gcloud for your chosen region:
gcloud config set run/region REGION
Replace REGION with the supported Cloud Run region of your choice.
Cloud Run locations
Cloud Run is regional, which means the infrastructure that
runs your Cloud Run services is located in a specific region and is
managed by Google to be redundantly available across
all the zones within that region.
Meeting your latency, availability, or durability requirements are primary
factors for selecting the region where your Cloud Run services are run.
You can generally select the region nearest to your users but you should consider
the location of the other Google Cloud
products that are used by your Cloud Run service.
Using Google Cloud products together across multiple locations can affect
your service's latency as well as cost.
Cloud Run is available in the following regions:
Subject to Tier 1 pricing
asia-east1
(Taiwan)asia-northeast1
(Tokyo)asia-northeast2
(Osaka)europe-north1
(Finland)Low CO2
europe-southwest1
(Madrid)Low CO2
europe-west1
(Belgium)Low CO2
europe-west4
(Netherlands)europe-west8
(Milan)europe-west9
(Paris)Low CO2
me-west1
(Tel Aviv)us-central1
(Iowa)Low CO2
us-east1
(South Carolina)us-east4
(Northern Virginia)us-east5
(Columbus)us-south1
(Dallas)us-west1
(Oregon)Low CO2
Subject to Tier 2 pricing
asia-east2
(Hong Kong)asia-northeast3
(Seoul, South Korea)asia-southeast1
(Singapore)asia-southeast2
(Jakarta)asia-south1
(Mumbai, India)asia-south2
(Delhi, India)australia-southeast1
(Sydney)australia-southeast2
(Melbourne)europe-central2
(Warsaw, Poland)europe-west12
(Turin)europe-west2
(London, UK)europe-west3
(Frankfurt, Germany)europe-west6
(Zurich, Switzerland)Low CO2
me-central1
(Doha)northamerica-northeast1
(Montreal)Low CO2
northamerica-northeast2
(Toronto)Low CO2
southamerica-east1
(Sao Paulo, Brazil)Low CO2
southamerica-west1
(Santiago, Chile)us-west2
(Los Angeles)us-west3
(Salt Lake City)us-west4
(Las Vegas)
If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Google Cloud console.
Retrieving the code sample
To retrieve the code sample for use:
Clone the sample app repository to your local machine:
git clone https://github.com/GoogleCloudPlatform/cloud-run-samples.git
Alternatively, you can download the sample as a zip file and extract it.
Change to the directory that contains the Cloud Run sample code:
cd cloud-run-samples/gcloud-report/
Reviewing the code
Generating a report and uploading to Cloud Storage
This shell script generates a report of Cloud Run services in the
current project and region and uploads the result to Cloud Storage. It lists
services whose name contains the provided string search
argument.
The script uses the gcloud run services list
command,
gcloud
advanced format options, and
gsutil
streaming transfer copy mode.
This script is safe to run as a service because repeated invocations of it update the report without further costly churn. Other scripts using the gcloud CLI can be more costly when invoked repeatedly, such as creating new Cloud resources or performing expensive tasks. Idempotent scripts, which yield the same result on repeated invocations, are safer to run as a service.
Invoking the script on HTTP request
This Go code sets up a web service that runs a shell script to generate a report. Since the search query is user input, the code validates it to ensure that it only contains letters, numbers, or hyphens to prevent malicious commands as input. This set of characters is narrow enough to prevent command injection attacks.
The web service passes the search parameter as an argument to the shell script.
A go.mod
file declares the application dependencies in a
go module:
Defining the container environment
The Dockerfile defines how the environment is put together for the service.
It is similar to the Dockerfile from the helloworld-shell quickstart,
except that the final container image is based on the gcloud
Google Cloud CLI image. This
allows our service to use gcloud
and gsutil
without custom installation and
configuration steps for the Google Cloud CLI.
Setting up the Cloud Storage bucket
Create a Cloud Storage bucket for uploading reports, where REPORT_ARCHIVE_BUCKET is a globally unique bucket name:
gsutil mb gs://REPORT_ARCHIVE_BUCKET
Setting up the service identity
In order to limit the privileges that the service has to other infrastructure, you create a service identity and customize the specific IAM permissions necessary to do the work.
In this case, the required privileges are permission to read Cloud Run services and permission to read from and write to the Cloud Storage bucket.
Create a service account:
gcloud iam service-accounts create gcloud-report-identity
Grant the service account permission to read Cloud Run services:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com \ --role roles/run.viewer
Grant the service account permission to read from and write to the Cloud Storage bucket:
gsutil iam ch \ serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com:objectViewer,objectCreator \ gs://REPORT_ARCHIVE_BUCKET
The limited access of this customized service identity prevents the service from accessing other Google Cloud resources.
Shipping the service
Shipping code consists of three steps:
- Building a container image with Cloud Build
- Uploading the container image to Container Registry
- Deploying the container image to Cloud Run.
To ship your code:
Build your container and publish on Container Registry:
gcloud builds submit --tag gcr.io/PROJECT_ID/gcloud-report
Where PROJECT_ID is your Google Cloud project ID, and
gcloud-report
is the name of your service.Upon success, a SUCCESS message displays the ID, creation time, and image name. The image is stored in Container Registry and can be re-used if desired.
Run the following command to deploy your service:
gcloud run deploy gcloud-report \ --image gcr.io/PROJECT_ID/gcloud-report \ --update-env-vars GCLOUD_REPORT_BUCKET=REPORT_ARCHIVE_BUCKET \ --service-account gcloud-report-identity \ --no-allow-unauthenticated
Replace PROJECT_ID with your Google Cloud project ID. Note that
gcloud-report
is part of the container name and the name of the service. The container image is deployed to the service and region (Cloud Run) that you configured previously under Setting up gcloud.The
--no-allow-unauthenticated
flag restricts unauthenticated access to the service. By keeping the service private you can rely on Cloud Run's built-in authentication to block unauthorized requests. For more details about authentication that is based on Identity and Access Management (IAM), see Managing access using IAM.Wait until the deployment is complete: this can take about half a minute. On success, the command line displays the service URL that you will use later to replace SERVICE_URL in the next section.
If you want to deploy a code update to the service, repeat the previous steps. Each deployment to a service creates a new revision and automatically starts serving traffic when ready.
See Managing access using IAM for how to grant Google Cloud users access to invoke this service. Project editors and owners automatically have this access.
Trying it out
Let's generate a report of Cloud Run services.
Use curl to send an authenticated request:
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL
Replace SERVICE_URL with the URL provided by Cloud Run after completing deployment.
If you created a new project and followed this tutorial, the output will be similar to:
Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-.-DATE.txt
The
.
in the file name is the default search argument as mentioned in the source code.To use the search feature, add a
search
argument to the request:curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL?search=gcloud
This query will return output similar to:
Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-gcloud-DATE.txt
Retrieve the file using the
gsutil
tool locally:gsutil cp gs://REPORT_FILE_NAME .
The
.
in the command means the current working directory.Replace REPORT_FILE_NAME with the Cloud Storage object name output in the previous step.
Open the file to see the report. It should look like this:

Improving robustness for the future
If you intend to further develop this service, consider rewriting in a more robust programming language and using the Cloud Run Admin API and the Cloud Storage client library.
You can examine the API calls being made (and see some authentication details)
by adding --log-http
to gcloud commands and -D
to gsutil commands.
Automating this operation
Now that the report of Cloud Run services can be triggered by an HTTP request, use automation to generate reports when you need them:
- Run this service on a schedule with Cloud Scheduler
- Create the report as a queued task or schedule in the future with Google Tasks
Clean up
If you created a new project for this tutorial, delete the project. If you used an existing project and wish to keep it without the changes added in this tutorial, delete resources created for the tutorial.
Deleting the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Deleting tutorial resources
Delete the Cloud Run service you deployed in this tutorial:
gcloud run services delete SERVICE-NAME
Where SERVICE-NAME is your chosen service name.
You can also delete Cloud Run services from the Google Cloud console.
Remove the gcloud default region configuration you added during tutorial setup:
gcloud config unset run/region
Remove the project configuration:
gcloud config unset project
Delete other Google Cloud resources created in this tutorial:
- Delete the Cloud Storage bucket REPORT_ARCHIVE_BUCKET
- Delete the container image named
gcr.io/PROJECT_ID/gcloud-report
from Container Registry. - Delete the invoker service account
gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com
What's next
- Reduce the dependencies of your service by replacing the
gcloud
andgsutil
tools with API calls: Uploading Objects, Cloud Run API Reference - Further enhance the security by using network ingress controlsto limit access to your service.
- Explore reference architectures, diagrams, and best practices about Google Cloud. Take a look at our Cloud Architecture Center.