Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



gcloud compute

This document describes the installation and usage of the gcloud compute command-line tool, which enables you to manage your Google Compute Engine resources. gcloud is a unified command line tool that includes improvements over the legacy gcutil tool, including statement autocompletion, in-place updating, extensive man-page style help, human-readable and machine-parsable output formats, and integration with Google Cloud SDK.

If you haven't already activated Google Compute Engine, follow the Sign Up steps. We also recommend that you review the Quickstart: Using gcloud compute . If you need help transitioning from using gcutil to gcloud compute , see Transitioning to gcloud compute .

Contents

Installing gcloud compute

To use gcloud compute , install the Google Cloud SDK if you have not already.

System Requirements : Google Cloud SDK runs on Windows, Mac OS X and Linux, and requires Python 2.7.x. Some of the individual tools bundled with Cloud SDK have more stringent requirements: using App Engine tools for Java development requires Java 1.7+.

Linux/Mac OS X

  1. Download and install Google Cloud SDK by running the following command in your shell or Terminal: 

    curl https://sdk.cloud.google.com | bash

    Or, you can download google-cloud-sdk.zip or google-cloud-sdk.tar.gz , unpack it, and launch the ./google-cloud-sdk/install.sh script.

  2. Restart your shell or Terminal.

Windows

Download the Google Cloud SDK installer for Windows

  1. Launch the downloaded GoogleCloudSDKInstaller.exe installer and follow the prompts.

  2. When the installation finishes, open a command prompt ( cmd.exe ) or the Google Cloud SDK Shell from Desktop or Start Menu.

For more installation options, see the Cloud SDK Overview .

Back to top

Authenticating to Google Compute Engine

Google Compute Engine uses OAuth2 to authenticate and authorize access. Before you can use gcloud compute , you must first authorize the Cloud SDK on your behalf to access your project and acquire an auth token. You won't need to repeat these steps unless you delete your stored credentials file or remove Google Compute Engine access to your Google account.

  1. Run gcloud auth login to request a token. This command prints a URL and tries to open a browser window to request access to your project. If a browser window can be opened, you will see the following output: 
    $ gcloud auth login
Your browser has been opened to visit:

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
Fauth%2Fappengine.admin+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery+https
%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcompute+https%3A%2F%2Fwww.googleapis.com%
Fauth%2Fdevstorage.full_control+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuser...

Created new window in existing browser session.

  2. If the Cloud SDK detects that a browser can not be opened (e.g., you are working on a remote machine) you will see the output below. Or, if you are working on a local machine and your browser doesn't automatically load the URL, then retry the gcloud auth login command with the --no-launch-browser flag. In either case, copy the authentication URL and paste it into a browser. 

    $ gcloud auth login --no-launch-browser
Go to the following link in your browser:

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
Fauth%2Fappengine.admin+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery+https
%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcompute+https%3A%2F%2Fwww.googleapis.com%
Fauth%2Fdevstorage.full_control+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuser...

Enter verification code:
  3. Grant access.

    In the browser window, review the application permissions and click Accept when you are ready. If you are working on a remove machine or used the --no-launch-browser flag, copy and paste the returned code on the command line after Enter verification code: . Otherwise, the code will automatically be sent to the command line without any additional action on your part.

  4. (Optional) Since a number of gcloud compute commands require the --project flag, you can instead set the default ID of the project you want to use for Google Compute Engine by running the following command: 
    $ gcloud config set project PROJECT

    To set your default project ID to a different one, re-run the command above at any time.

    Similarly, to unset your project ID, run: 

    $ gcloud config unset project

    You can also view your settings, including your project ID: 

    $ gcloud config list

Back to top

Getting help

The following commands show you how to access different types of help, from general help about gcloud compute , 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 .

Back to top

Setting a default zone and region

You can set default zone and region values for gcloud compute commands that take zone and regions as flags, such as instances create , target-pools describe , and target-instances delete . When you set default zone and region values, gcloud compute will use these values if you omit a zone or region flag for a command where it is required. gcloud compute uses the following order of precedence for what values of zone and region it uses:

  • Zone or region values you provide as a command line flag, --zone or --region .
  • Environment variables CLOUDSDK_COMPUTE_ZONE and CLOUDSDK_COMPUTE_REGION
  • Configuration properties set with gcloud config .

If a zone or region value was still not determined after the checks above, gcloud compute prompts you to provide a zone or region value.

To set configuration properties

To see what properties are configured use: 

$ gcloud config list

To see a list of available zones and regions you can use: 

$ gcloud compute zones list
$ gcloud compute regions list

To set a zone or region property, use: 

$ gcloud config set compute/zone ZONE
$ gcloud config set compute/region REGION

To remove the zone or region property, use: 

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

Points to keep in mind:

  • If a list command has a --zones or --regions flag (for example, operations list ), gcloud compute does not use the zone config property or environment variable, even if they exist.

  • If you are working with gcloud compute interactively, it may be easier to work without setting a zone or region property and let gcloud compute prompt you to choose a value when it is required.

Back to top

Common gcloud compute commands for working with instances

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

Creating 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 --zone us-central1-a

If you omit the --zone flag and no default zone is set, gcloud compute prompts you to provide the zone. For more information, see Setting a default zone and region .

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

Listing 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 --regexp my-.*

Fore more information about working with the --regexp flag and using regular expressions, 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 .

Connecting to instances

gcloud compute makes connecting to your instances easy. The gcloud compute ssh and gcloud compute copy-files 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 copy-files ~/file-1 my-instance:~/remote-destination --zone us-central1-a

The copy-files 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 copy-files my-instance:~/file-1 ~/local-destination --zone us-central1-a

Both the gcloud compute ssh and gcloud compute copy-files 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.my-project
    HostName 107.178.220.224
    IdentityFile ~/.ssh/google_compute_engine
    UserKnownHostsFile=/dev/null
    CheckHostIP=no
    StrictHostKeyChecking=no

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 "my-project", you can use the OpenSSH ssh client as follows: 

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

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

$ scp my-instance.us-central1-a.my-project:~/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 detailed 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-from 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
...
metadata:
  fingerprint: eU448B6JGQw=
  items:
  - key: build-num
    value: '4.32'
  kind: compute#metadata
...

To change existing metadata or add new metadata, use add-metadata . 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 Google 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:

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

    Listing operations

    Operations are a record of changes to your Google 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 --zones us-central1-a us-central1-b

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

    Back to top

    Next steps

    That's it, you can now start using gcloud compute on your own! Here are some ideas to get you started:

    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 .

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.