gcloud compute

The gcloud command-line tool lets you manage your Compute Engine resources and is an alternative to using the Compute Engine API.

The gcloud tool is part of the Cloud SDK and is a unified command-line tool that includes features like statement autocompletion, in-place updating, extensive man page style Help, human-readable and machine-parsable output formats, and integration with Cloud SDK.

If you don't have a command prompt readily available, try using Cloud Shell. Cloud Shell is automatically updated with the latest Cloud SDK.

If you have never used Compute Engine, get started with either the Linux quickstart or the Windows quickstart.

Install or update gcloud compute

For information about installing and updating gcloud compute, see the Google Cloud SDK documentation.

Set up gcloud compute

Compute Engine uses OAuth2 to authenticate and authorize access. Before you can use gcloud compute, you must authorize the Cloud SDK on your behalf to access your project and acquire an authorization token.

  1. Run gcloud init to start the authentication process.

    gcloud init

    You see the following output:

    Welcome! This command will take you through the configuration of gcloud.
    Your current configuration has been set to: [default]
    You can skip diagnostics next time by using the following flag:
    gcloud init --skip-diagnostics
    Network diagnostic detects and fixes local network connection issues.
    Checking network connection...done.
    Reachability Check passed.
    Network diagnostic passed (1/1 checks passed).
    Choose the account you would like to use to perform operations for
    this configuration:
     [1] PROJECT_NUMBER-compute@developer.gserviceaccount.com
     [2] Log in with a new account
    Please enter your numeric choice:
  2. Choose the credentials for this configuration:

    • Enter 1 to use a default service account.
    • Enter 2 to use your Google Cloud account. This is the recommended method.

    If the Cloud SDK detects that a browser can't be opened (for example, you are working on a remote machine) you see the following output:

    Go to the following link in your browser:
    Enter verification code:

    Copy the authentication URL and paste it into a browser. If you are working on a local machine and your browser doesn't automatically load the URL, retry the gcloud init command with the --console-only flag.

    gcloud init --console-only
  3. Grant access.

    In the browser window, review the application permissions and click Accept when you are ready. If you are working on a remote machine or used the --console-only flag, copy and paste the returned code on the command line after Enter verification code:. Otherwise, the code is automatically sent to the command-line tool.

  4. Choose the default project for this configuration.

    After setting up your credentials, the gcloud tool prompts you for a default project.

    You are logged in as: [EMAIL_ADDRESS].
    This account has a lot of projects! Listing them all can take a while.
     [1] Enter a project ID
     [2] Create a new project
     [3] List projects
    Please enter your numeric choice:
    • Enter 1 if you know your project ID.
    • Enter 2 if you want to create a new project.
    • Enter 3 if you want to view a list of projects.

    After setting your default project, all of your gcloud compute commands use the default project ID unless you override it by using the --project flag or set the CLOUDSDK_CORE_PROJECT environment variables. If you do not set a default project or environment variable, you must include a --project flag in each gcloud compute command that you run.

  5. Optional: Set the default region and zone

    After selecting your project ID, the gcloud tool prompts you to configure a default region and zone.

    Your current project has been set to: [PROJECT_ID].
    Do you want to configure a default Compute Region and Zone? (Y/n)?

    Setting the default project is optional. A zone or a region is required for working with resources that belong to a zone or a region (for example, if you use the gcloud tool to work with a VM instance, you must specify the instance's zone). By setting a default zone and region, you won't have to provide it with each request. You can always manually override or change these default settings, as explained in Default properties.

    If you want to set the default project, enter Y. You see the following output:

    If you do not specify a zone via a command line flag while working
    with Compute Engine resources, the default is assumed.
     [1] us-east1-b
     [2] us-east1-c
     [3] us-east1-d
     [4] us-east4-c
     [5] us-east4-b
     [6] us-east4-a
     [7] us-central1-c
    Too many options [74]. Enter "list" at prompt to print choices fully.
    Please enter numeric choice or text value (must exactly match list

    Enter the numeric value of the zone you want to set, or enter list to see all zones. Then, you see the following output:

    Your project default Compute Engine zone has been set to [ZONE].
    You can change it by running [gcloud config set compute/zone NAME].
    Your project default Compute Engine region has been set to [REGION].
    You can change it by running [gcloud config set compute/region NAME].
    Your Google Cloud SDK is configured and ready to use!
    * Commands that require authentication will use EMAIL_ADDRESS by default
    * Commands will reference project `PROJECT_ID` by default
    * Compute Engine commands will use region `REGION` by default
    * Compute Engine commands will use zone `ZONE` by default
    Run `gcloud help config` to learn how to change individual settings
    This gcloud configuration is called [PROJECT_ID]. You can create additional
    configurations if you work with multiple accounts and/or projects.
    Run `gcloud topic configurations` to learn more.
    Some things to try next:
    * Run `gcloud --help` to see the Cloud Platform services you can
    interact with. And run `gcloud help COMMAND` to get help on any gcloud
    * Run `gcloud topic --help` to learn about advanced features of the SDK
    like arg files and output formatting

Using configurations

The gcloud tool uses the concept of configurations to help you manage your credentials for different accounts. Each configuration contains the email account to authenticate with and specific settings like the default project ID and default zone setting. The gcloud tool automatically comes installed with a default configuration. This is the configuration whose credentials are used to authenticate to Google Cloud services.

For most users, just using the default configuration is enough. If you have use cases that require that you switch between accounts, you can create more configurations that you can alternate between.

Default properties

The metadata server contains metadata information about a project, including the project ID, project name, and so on. You can use the gcloud command-line tool to query the metadata server to get and use information about the project.

View default properties

To see what your default properties are, run the following command by using the gcloud command-line tool. Replace PROJECT_ID with your project ID.

gcloud compute project-info describe --project PROJECT_ID

View default region and zone

To see what your default region and zone settings are, run the following commands:

gcloud config get-value compute/zone
gcloud config get-value compute/region

If the google-compute-default-region or google-compute-default-zone responses are (unset), that means no default zone or region is set.

  • If no default is set, then the gcloud tool prompts you for a region and zone with each request.

  • If a default is set, the gcloud tool automatically uses the default value for all of the gcloud tool requests you make unless you manually override the default settings.

To change, set, or override the default properties, use the methods below.

Change your default zone and region in the metadata server

If you specify a default region and zone for your project, then Compute Engine sets these values in the metadata server for your project.

Set default regions and zones by using:

  • google-compute-default-zone
  • google-compute-default-region

For example:

gcloud compute project-info add-metadata \
    --metadata google-compute-default-region=europe-west1,google-compute-default-zone=europe-west1-b

The gcloud command-line tool only picks up on new default zone and region changes after you rerun the gcloud init command. After updating your default metadata, run gcloud init to reinitialize your default configuration.

Set default zone and region in your local client

You can manually choose a different zone or region without updating the metadata server by setting these properties locally on your gcloud client.

First, make sure you are using the configuration for which you want this set these properties. Each configuration has its own settings. To switch between configurations, run the following command:

gcloud config configurations activate CONFIGURATION_NAME

Next, to set a zone or region property in the client, run:

gcloud config set compute/zone ZONE

gcloud config set compute/region REGION

To remove a default property altogether, use the unset command.

gcloud config unset compute/zone
gcloud config unset compute/region

Note that removing the default property altogether will result in the gcloud tool prompting for a zone or region for every command you run.

Set default values in environment variables

You can set environment variables that supply values to gcloud compute commands. Environment variables override default properties that you set with the gcloud config commands, but do not override explicit flags like --zone or --region.

Use the export command to set the project, zone, and region variables.
To make these environment variables permanent, include these commands in your ~/.bashrc file and restart your terminal.
Use the set command to set the project, zone, and region variables.

You can override environment variables by including specific --zone or --region flags with your commands.

Set values on each request

You can override default properties by including specific --zone or --region flags with each of your commands. For example:

gcloud compute instances create example-instance --zone us-central1-f

These flags only work for the single command you use it with. The flags do not change any default settings you have, but simply overrides it for that request.

Order of precedence for default properties

The gcloud command-line tool evaluates default properties in the following order for each configuration:

  • If you provide an explicit --zone or --region or --project flag, the flag overrides all other settings for that single request.
  • If the default zone and region properties are defined only in the metadata server, the gcloud command-line tool sets your local gcloud client to these properties when you run gcloud init. For subsequent requests, the gcloud tool prompts you for the zone.
  • If the default zone and region properties are defined in both the metadata server and on the local client for that configuration, the gcloud tool uses the default properties on the local client.
  • If the default zone and region properties are defined in the metadata server, the local client, and in environment variables, the gcloud tool uses the default properties in the environment variables, regardless of which configuration you are using.

Common gcloud compute commands

Below are examples of common tasks when working with instances. For more details about working with instances in general, see Instances.

Create instances

Use the instances create command to create a new instance. For example, the following command creates an instance named "my-instance" in the "us-central1-a" zone.

gcloud compute instances create my-instance

If you omit the --zone flag, the gcloud tool can infer your desired zone based on your default properties.

Other required instance settings, like machine type and image, if not specified in the create command, are set to default values. You can see the default values by displaying help for the create command:

gcloud compute instances create --help

List instances

There are a number of ways to list your instances using the instances list command. You can create a human-readable, tabular output with the following command:

gcloud compute instances list

You can use regular expressions to narrow the list of instances returned by name. For example, the following command returns all instances whose names start with "my-".

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

Fore more information about listing and filtering resources, see Fetching resources.

To return details about one instance, use the instances describe command. For example, the following command returns information about "my-instance".

gcloud compute instances describe my-instance --zone us-central1-a

The previous command returns results in YAML format. You can use the --format flag to change how the results are displayed. For more examples of getting and listing resources, including instances, see Fetching Resources.

Connect to instances

gcloud compute makes connecting to your instances easy. The gcloud compute ssh and gcloud compute scp commands provide wrappers around around SSH and SCP, which takes care of authentication and the mapping of instance name to IP address.

For example, to ssh in to "my-instance" in the "us-central1-a" zone, you can use:

gcloud compute ssh my-instance --zone us-central1-a

To copy the local file "file-1" to "my-instance" in the "us-central1-a" zone, you can use:

gcloud compute scp ~/file-1 my-instance:~/remote-destination --zone us-central1-a

The scp command can also be used to copy files from an instance to your local machine. For example, to create a local copy of "file-1", which is on the instance "my-instance" in the "us-central1-a" zone, you can use:

gcloud compute scp my-instance:~/file-1 ~/local-destination --zone us-central1-a

Both the gcloud compute ssh and gcloud compute scp commands, by default, use the private key file located at "~/.ssh/google_compute_engine". If you don't want to use this key file, you can specify a different key file by specifying a different location with the --ssh-key-file flag. For example, you might already have a private key you want to use, or you might want to use different private keys with different projects.

Using SSH-based programs directly

If you prefer to use ssh and scp directly, gcloud compute can generate an SSH configuration file that contains host aliases for your instances with authentication configuration. To do this, run:

gcloud compute config-ssh

Here's an example of one alias added to the SSH configuration file (~/.ssh/config):

Host my-instance.us-central1-a.myproject
IdentityFile ~/.ssh/google_compute_engine

You can specify an alternative, per-user SSH config file by using the --ssh-config-file flag.

Every time you add or remove an instance, you should rerun the config-ssh command.

After updating your SSH config files with the config-ssh command, you can use any SSH-based program to access your instances. For example, for the instance named "my-instance", in the "us-central1-a" zone, in the project named "myproject", you can use the OpenSSH ssh client as follows:

$ ssh my-instance.us-central1-a.myproject

To make a local copy of the file "file-1" on the instance, you can use the scp client as follows:

$ scp my-instance.us-central1-a.myproject:~/file-1 .

Working with metadata

You can set custom metadata for an instance or project outside of the server-defined metadata. This is useful for passing in arbitrary values to your project or instance that can be queried by your code on the instance. This section shows a few common metadata operations. For more information about working with metadata, see Storing and Retrieving Metadata.

Adding and removing instance metadata

You can configure instance metadata with gcloud compute when you create an instance using the create command, or with an existing instance using the add-metadata and remove-metadata commands. Metadata are specified as key/value pairs separated with an equals sign ("=") using the --metadata flag. Or, metadata can be read from a local file using the --metadata-from-file flag.

For example, to add the custom metadata keys "role", "unique-id", and "build-num" to an existing instance named "my-instance" in the "us-central1-a" zone, you can use:

gcloud compute instances add-metadata my-instance \
    --zone us-central1-a \
    --metadata role=worker unique-id=1234 build-num=4.32

To remove the custom metadata keys "role" and "unique-id", you can use:

gcloud compute instances remove-metadata my-instance \
    --zone us-central1-a \
    --keys role unique-id

After adding and removing metadata from an existing instance, you can see your changes by running:

gcloud compute instances describe my-instance --zone us-central1-a
  fingerprint: eU448B6JGQw=
  - key: build-num
    value: '4.32'
  kind: compute#metadata

To change existing metadata or add new metadata, use the add-metadata command. Instance metadata updates are additive. This means that you need to only specify the metadata keys that you want to add or change. If you specify an existing key, then the key's value will be updated with the new value.

For images that have Compute Engine tools installed on them, there are two metadata keys that are reserved for startup scripting functionality:

  • startup-script: Indicates script content that is executed when the instance starts. For longer script content, you can use the --metadata-from-file flag to pass in a path to a file that contains the script content.
  • startup-script-url: Indicates that a script at the specified publicly-accessible location is executed when the instance starts.

For example, to create an instance named "my-instance" in the "us-central1-a" zone, with startup script content specified with the --metadata flag, you can use:

gcloud compute instances create my-instance --zone us-central1-a \
    --metadata startup-script="echo 'hello world'"

If you SSH in to "my-instance" and check the system log (/var/log/syslog) you will see the result of the startup script.

With an existing instance named "my-instance" you can add the following startup script from a local file using the --metadata-from-file flag:

gcloud compute instances add-metadata my-instance \
    --metadata-from-file startup-script=/local/path/to/script/startup

In this example, the startup script is run when the instance reboots, for example, when you use gcloud compute instances reset.

Adding and removing project-level metadata

Project-level metadata is accessible by all instances in a project. By default, a project has reserved project-level metadata. You can also add and remove custom project-level metadata. Like instance metadata, project metadata updates are additive. This means that you need to only specify the metadata keys that you want to add or change. If you specify an existing key, then the key's value will be updated with the new value.

To see the existing project-level metadata, use the project-info describe command:

gcloud compute project-info describe

The following command adds two pieces of project-wide metadata.

gcloud compute project-info add-metadata \
    --metadata-from-file startup-script=/local/path/to/script
    --metadata startup-id=1234

Note that the startup-script key is reserved and means that the content from the specified local file is to be run when instances start.

To remove the two pieces of metadata you just added, use:

gcloud compute project-info remove-metadata --keys startup-script startup-id

Deleting instances

To delete the instance named "my-instance" in the "us-central1-a" zone, you can use the instances delete command:

gcloud compute instances delete my-instance --zone us-central1-a

When you create an instance, a persistent disk is also created. This disk counts towards your persistent disk quota and incurs monthly persistent disk charges. The instances delete command to delete an instance, by default, removes the persistent disk associated with the instance. To override this behavior, you can:

  • Use the --keep-disks flag of the instances delete command.
  • Configure the disk to not be auto-deleted. After you create an instance, and anytime before you delete the instances, you can use the instances set-disk-auto-delete command to preserve the persistent disk. Note that the --delete-disks flag of the instances delete commmand will delete disks regardless of the auto-delete configuration.

For more information, see Setting the auto-delete state of a persistent disk.

Listing operations

Operations are a record of changes to your Compute Engine resources. To get a list of all operations in a project, you can use the operations list command:

gcloud compute operations list

Operations have scopes that can be used to narrow the operations returned in a list request. For example, you can use the --global, --zones, and --regions flags to refine your results. The following command returns only the operations in the us-central1-a and us-central1-b zones:

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

For more examples of getting and listing resources, including operations, see Fetching resources.

Getting help pages

The following commands show how to access different types of help, from general help about the gcloud computecommand, to specific help about a resource group (instances) or a command (create). Comprehensive help for all resources and commands follows this pattern:

gcloud compute --help
gcloud compute instances --help
gcloud compute instances create --help

Quick help can be obtained by using the -h flag instead of the --help flag. You can also review all of the comprehensive help at Cloud SDK reference.

For comprehensive help with commands specifically for configuring the gcloud tool, run:

<pre class="devsite-click-to-copy>gcloud topic <var>TOPIC</var></pre>

Where TOPIC is the applicable topic for which you want to get help. For a list of topics you can get help for, see gcloud topic reference documentation.

What's next?