gcloud compute usage tips

This page contains tips that might be useful when you use the gcloud command-line tool to manage your Compute Engine resources. For a complete list of all available gcloud compute flags and commands, you can use the built-in command help (--help) or the published reference documentation, or the gcloud core documentation.

Before you begin

Fetching information about resources

You can fetch information about Compute Engine resources in two ways: using the list command to return a list of resources and using the describe command to return details about one specific resource.

Fetching resources with list commands

The list commands are designed to return a human-readable table of the most relevant data for the requested resources. You can optionally filter your results to return a shorter list with more relevant results.

Regular expression filtering for names
You can use RE2 syntax to match resource names (for example, instance or disk names). Refer to the gcloud compute instances list.
Command Flags

The maximum number of results to return. This flag is particularly useful when used with the --sort-by flag described in the Fetching resources with describe commands section.

--sort-by SORT_BY

A field to sort by, if applicable. To perform a descending-order sort, prefix the value with a tilde ("~").

Fetching resources with describe commands

The describe commands are designed for displaying data about one resource. You must provide the name of the resource in the describe command. If you can't remember the resource name, you can run a list command to get a list of resources. For example, the following two commands illustrate a scenario when you can list images to get an image name and its associated project so that you can provide these as inputs to a describe command:

gcloud compute images list
NAME                                PROJECT        FAMILY     DEPRECATED STATUS
centos-7-v20170620                  centos-cloud   centos-7              READY
debian-9-stretch-v20170619          debian-cloud   debian-9              READY
gcloud compute images describe debian-9-stretch-v20170619 --project debian-cloud

The default output from describe commands is YAML format, but you can use the --format flag to choose between JSON, YAML, and text output formats. JSON formatted output can be useful if you are parsing the output, while text formatted output puts each property on a separate line.

gcloud compute regions describe us-central1 --format json
  "creationTimestamp": "2013-09-06T10:36:54.847-07:00",
  "description": "us-central1",
  "id": "6837843067389011605",
  "kind": "compute#region",
  "name": "us-central1",
  "status": "UP",
  "zones": [


Examples of list commands

When you list resources, you get an easy-to-read table of summary data. For example, to return summary data about instances in your project, use the instances list command:

gcloud compute instances list
example-instance   asia-east1-b  e2-standard-2  RUNNING
example-instance2  us-central1-a e2-standard-2  RUNNING
test-instance      us-central1-a e2-standard-2  RUNNING

You can filter results from list commands with regular expressions by including the --filter flag with a key ~ value operator. For example, filter the list of instances to include only the instances with "test" in the instance name:

gcloud compute instances list --filter="name ~ .*test.*"
test-instance  us-central1-a e2-standard-2  RUNNING

To return a list of zone operations that have a status of DONE and do not have an httpStatus of 200, apply a zone filter on an operations list command, then grep the results:

gcloud compute operations list --filter="zone:(us-central1-a)" | grep DONE | grep 200
NAME                                                    HTTP_STATUS TYPE   TARGET                               STATUS
operation-1397752585735-4f73fa25b4b58-f0920fd5-254d709f 400         delete us-central1-a/disks/example-instance DONE
operation-1398357613036-4f7cc80cb41e0-765bcba6-34bbd040 409         insert us-central1-a/instances/i-1          DONE
operation-1398615481237-4f8088aefbe08-cc300dfa-2ce113cf 409         insert us-central1-a/instances/i-2          DONE

To get a list of list of disks in us-central1-a, sorted in descending order by name (--sort-by ~NAME), use a disks list command:

gcloud compute disks list --sort-by ~NAME --filter="zone:(us-central1-a)"

In some scenarios, you may want to have the full URI link to the resource, such as requests where you are passing the output from a list command to another command or application that takes a list of resource links. To show full URI resource links, use the --uri flag with a list command.

gcloud compute instances list --uri --filter="name~'^example-.*'"

To use the previous list command output within a command that deletes instances, use:

gcloud compute instances delete $(gcloud compute instances list --uri --filter="name~'^example-.*'")

Examples of describe commands

To get details about just one instance, specify the instance, including zone. For example, to return information about the instance named "example-instance" in the "asia-east1-b" zone, you can use instances describe command:

gcloud compute instances describe example-instance --zone asia-east1-b

By default, this returns YAML output. To change the output to JSON or text (one property per line) use the --format flag. For example, to return text output for the same instance, use:

gcloud compute instances describe example-instance --zone asia-east1-b --format text
canIpForward:                                False
creationTimestamp:                           2014-04-19T06:43:04.087-07:00
disks[0].autoDelete:                         False
disks[0].boot:                               True
disks[0].deviceName:                         example-instance

To get details about a specific operation, use the operations list command to find the fully qualified URI of the operation:

gcloud compute operations list --filter="zone:(us-central1-a)"
NAME                                                    TYPE   TARGET                                      HTTP_STATUS STATUS
operation-1406155165815-4fee4032850d9-7b78077c-a170c5c0 delete us-central1-a/instances/example-instance    200         DONE
operation-1406155180632-4fee4040a67c1-bf581ed8-ab5af2b8 delete us-central1-a/instances/example-instance-2  200         DONE

Then use the URI in an operations describe command:

gcloud compute operations describe \
operation-1406155165815-4fee4032850d9-7b78077c-a170c5c0 --zone us-central1-a
endTime: '2014-07-23T15:40:02.463-07:00'
id: '31755455923038965'
insertTime: '2014-07-23T15:39:25.910-07:00'
kind: compute#operation
name: operation-1406155165815-4fee4032850d9-7b78077c-a170c5c0
operationType: delete
progress: 100

The following command gets instance settings in JSON format (--format json).

gcloud compute instances describe example-instance \
    --zone us-central1-a
    --format json
   "name": "example-instance",
   "networkInterfaces": [
      "accessConfigs": [
          "kind": "compute#accessConfig",
          "name": "external-nat",
          "natIP": "",
          "type": "ONE_TO_ONE_NAT"
      "name": "nic0",
      "network": "https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default",
      "networkIP": ""
   "status": "RUNNING"