This page contains tips that might be useful when you use thegcloudcommand-line tool to manage your Compute Engine resources. For acomplete list of all availablegcloud compute flags andcommands, you can use the built-in command help (--help) or the publishedreference documentation, orthegcloud core documentation.

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

Fetching information about resources

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

Fetching resources withlist commands

Thelist commands are designed to return a human-readable table of themost relevant data for the requested resources. You can optionallyfilter your results to return a shorterlist with more relevant results.

Regular expression filtering for names

You can useRE2 syntax to matchresource names (for example, instance or disk names). Refer to thegcloud compute instances listcommand.

Command Flags

--limit

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

--sort-by SORT_BY

A field to sort by, if applicable. To perform a descending-order sort, prefixthe value with a tilde ("~"). This flag interacts with other flags that areapplied in this order:--flatten,--sort-by,--filter,--limit.

Fetching resources withdescribe commands

Thedescribe commands are designed for displaying data about one resource. Youmust provide the name of the resource in thedescribe command. If you can'tremember the resource name, you can run alist command to get a list ofresources. For example, the following two commands illustrate a scenario whenyou can list images to get an image name and its associated project so that youcan provide these as inputs to adescribe 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 fromdescribe commands is YAML format, but you can usethe--format flag to choose between JSON, YAML, and text output formats.JSON formatted output can be useful if you are parsing the output, while textformatted output puts each property on a separate line.

gcloudcomputeregionsdescribeus-central1--formatjson

{  "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/myproject/zones/us-central1-a",    "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-b",    "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f"  ]}

Examples

Examples oflist commands

When you list resources, you get an easy-to-read table ofsummary data. For example, to return summary data about instances in yourproject, use theinstances list command:

gcloud compute instances list

NAME               ZONE          MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP     STATUSexample-instance   asia-east1-b  e2-standard-2 10.240.95.199  107.167.182.44  RUNNINGexample-instance2  us-central1-a e2-standard-2 10.240.173.254 23.251.148.121  RUNNINGtest-instance      us-central1-a e2-standard-2 10.240.118.207 23.251.153.172  RUNNING

You can filter results fromlist commands with regular expressions byincluding the--filter flag with akey ~ value operator. For example, filter the list of instances to includeonly the instances with "test" in the instance name:

gcloud compute instances list --filter="name ~ .*test.*"

NAME           ZONE          MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP     STATUStest-instance  us-central1-a e2-standard-2 10.240.118.207 23.251.153.172  RUNNING

To return a list of zone operations that have astatus ofDONE and don'thave anhttpStatus of200, apply azone filter on anoperations list command, thengrep the results:

gcloud compute operations list --filter="zone:(us-central1-a)" | grep DONE | grep -v 200

NAME                                                    HTTP_STATUS TYPE   TARGET                               STATUSoperation-1397752585735-4f73fa25b4b58-f0920fd5-254d709f 400         delete us-central1-a/disks/example-instance DONEoperation-1398357613036-4f7cc80cb41e0-765bcba6-34bbd040 409         insert us-central1-a/instances/i-1          DONEoperation-1398615481237-4f8088aefbe08-cc300dfa-2ce113cf 409         insert us-central1-a/instances/i-2          DONE

To get a list of list of disks inus-central1-a, sorted in descending order byname (--sort-by ~NAME), use adisks 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 theresource, such as requests where you are passing the output from alistcommand to another command or application that takes a list of resource links.To show full URI resource links, use the--uri flag with alist command.

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

https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance1https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance2

To use the previouslist command output within a command that deletesinstances, use:

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

Examples ofdescribe commands

To get details about just one instance, specify the instance, including zone.For example, to return information about the instance named "example-instance" inthe "asia-east1-b" zone, you can useinstances 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 propertyper line) use the--format flag. For example, to return text output for thesame instance, use:

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

---canIpForward:                                FalsecreationTimestamp:                           2014-04-19T06:43:04.087-07:00disks[0].autoDelete:                         Falsedisks[0].boot:                               Truedisks[0].deviceName:                         example-instance...

To get details about a specific operation, use theoperations list commandto find the fully qualified URI of the operation:

gcloud compute operations list --filter="zone:(us-central1-a)"

NAME                                                    TYPE   TARGET                                      HTTP_STATUS STATUSoperation-1406155165815-4fee4032850d9-7b78077c-a170c5c0 delete us-central1-a/instances/example-instance    200         DONEoperation-1406155180632-4fee4040a67c1-bf581ed8-ab5af2b8 delete us-central1-a/instances/example-instance-2  200         DONE...

Then use the URI in anoperations describecommand:

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#operationname: operation-1406155165815-4fee4032850d9-7b78077c-a170c5c0operationType: deleteprogress: 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/myproject/global/networks/default",      "networkIP": "10.240.111.51"    }   ],   ...   "status": "RUNNING"   ...}

Checking which user you are authorized as

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

gcloud auth list

Revoking a refresh token

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

gcloud auth revoke

This will force you to use re-authenticate usinggcloud init.

You can also revoke permission for the gcloud CLI to access yourresources. Youmight do this, if your refresh tokens are compromised, for example. To revokepermission for thegcloud CLI:

1. Log into yourGoogle Account page.
2. ClickSecurity and then clickView allin theAccount permissions section.
3. SelectGoogle Cloud SDK and clickRevoke Access.

Rebooting an instance

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

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

For information about the implications of a reset, read theReset an instance documentation.