This document describes usage tips for working with gcloud compute . 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 .

Contents

• Fetching information about resources
  • Fetching resources with `list` commands
  • Fetching resources with `describe` commands
  • Examples
    • List command examples
    • Describe command examples
• Checking which user you are authorized as
• Saving and reusing flag values
• Revoking a refresh token
• Rebooting an instance

Fetching information about resources

You can fetch information about Google 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 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 based on a set of criteria 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). Specify a regular expression using the --regexp flag. For example, when listing instances, the following command returns all instances with "test" in the name.

$ gcloud compute instances list --regexp .*test.*

You can also specify multiple regular expressions. For example, the following command returns all instances with "test" in the name, as well as those with a name that starts with "worker".

$ gcloud compute instances list --regexp "(.*test.*)|(worker.*)"

Command Flags

--limit

The maximum number of results to return. This flag is particularly useful when used with the --sort-by flag described in the Controlling output formatting section.

--sort-by SORT_BY

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

--zones ZONE [ZONE ...]

One or more zones to use to narrow the returned resource list. Separate multiple zones with a space. If this flag is not provided, the default is to return resources from all zones. The --zones flag can only be used for zonal resources like instances, disks, and operations. The config/zone configuration property is not used to resolve values for this flag. For more information, see Setting a default zone and region .

--regions REGION [REGION ...]

One or more regions to use to narrow the returned resource list. Separate multiple regions with a space. If this flag is not provided, the default is to return resources from all regions. The --regions flag can only be used for regional resources like addresses, The config/region configuration property is not used to resolve values for this flag. For more information, see Setting a default zone and region .

Whenever possible, you specify zones or regions as part of your list commands. Doing so results in the least number of API calls behind-the-scenes. When you don't specify a zone or region in your list commands, gcloud compute pulls all resources in all zones and regions, which can be slow.

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        DEPRECATED STATUS
centos-6-v20140718                  centos-cloud              READY
debian-7-wheezy-v20140718           debian-cloud              READY
...
$ gcloud compute images describe debian-7-wheezy-v20140718 --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": [
    "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
    "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-b",
    "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f"
  ]
}

Examples

List command examples

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

NAME               ZONE          MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP     STATUS
example-instance   asia-east1-b  n1-standard-1 10.240.95.199  107.167.182.44  RUNNING
example-instance2  us-central1-a n1-standard-1 10.240.173.254 23.251.148.121  RUNNING
test-instance      us-central1-a n1-standard-1 10.240.118.207 23.251.153.172  RUNNING

List commands support using RE2 regular expressions to match resource names. For example, to list all the instances with "test" in the instance name, use:

$ gcloud compute instances list --regexp .*test.*

NAME           ZONE          MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP     STATUS
test-instance  us-central1-a n1-standard-1 10.240.118.207 23.251.153.172  RUNNING

To return a list of operations that have a status of DONE and do not have an httpStatus of 200 , use the operations list command:

$ gcloud compute operations list --zones us-central1-a | grep DONE | grep -v 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 sorted in descending order by name ( --sort-by ~NAME ) for the us-central1-a zone use disks list command:

$ gcloud compute disks list --sort-by ~NAME --zones 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 --regexp my-.*
https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/example-instance1
https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/example-instance2

To use the previous list command in a command to delete several instances at once, use:

$ gcloud compute instances delete $(gcloud compute instances list --uri --regexp my-.*)

Describe command examples

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, and then use it in an operations describe command:

$ gcloud compute operations list --zones 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
...

$ 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": "107.167.187.66",
          "type": "ONE_TO_ONE_NAT"
        }
      ],
      "name": "nic0",
      "network": "https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default",
      "networkIP": "10.240.111.51"
    }
   ],
   ...
   "status": "RUNNING"
   ...
}

Back to top

Checking which user you are authorized as

Use the following command to find out which account you are authorizes as, use:

$ gcloud auth list

Back to top

Revoking a refresh token

To revoke the credentials for an account on the machine where you are using the Cloud SDK, use:

$ gcloud auth revoke

This will force you to use re-authenticate using gcloud auth login .

You can also revoke permission for the Cloud SDK to access your resources. You might do this, if your refresh tokens are compromised, for example. To revoke permission for the Cloud SDK:

1. Log into your Google account page.
2. Click on Security and then click View all in the Account permissions section.
3. Select Google Cloud SDK and click Revoke Access .

Back to top

Rebooting an instance

To reset an instance named "example-instance" in the "us-central1-a" zone, use the instances reset command:

$ gcloud compute instances reset example-instance --zone us-central1-a

For information about the implications of a reset, review the Instances documentation.

Back to top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .