The gcloud compute
command-line tool enables you to easily manage your
Compute Engine resources in a friendlier format than 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 have never used Compute Engine, get started with one of the Quickstart guides
Install or update gcloud compute
To install the latest version of
gcloud compute
, install the Cloud SDK.To update to the latest version of
gcloud compute
, see gcloud components update.
Set up gcloud compute
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.
If you are using the gcloud
command-line tool for the first time, gcloud
automatically uses
the default
configuration. For most cases, you only need
the default
configuration.
Run
gcloud init
to start the authentication process. Hit enter when prompted.The 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 init
Welcome! This command will take you through the configuration of gcloud. Your current configuration has been set to: [default] ... To continue, you must login. Would you like to login (Y/n)? y 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%2...
If the Cloud SDK detects that a browser can't be opened (e.g., you are working on a remote machine) you 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 init
command with the--console-only
flag.gcloud init --console-only
Copy the authentication URL and paste it into a browser. Then paste the verification code back into the terminal.
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%2... Enter verification code:
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.Choose the credentials for this configuration.
After setting up your credentials,
gcloud
prompts for a default project for this configuration. Select a project ID from the list.After you set this property, all of your
gcloud compute
commands use the default project ID unless you override it with the--project
flag or set theCLOUDSDK_CORE_PROJECT
environment variable. If you do not set a default project or environment variable, you must include a--project
flag in eachgcloud compute
command that you run.
A zone or a region is required for working with resources
that belong to a zone or a region (for example, any time you manipulate a
virtual machine instance, you must specify a zone). By setting a default zone
and region, gcloud
can infer this information without requiring you to
provide it with each request. You can always manually override or
change these default settings.
For more information, read Set default properties.
Using configurations
gcloud
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, default
zone setting, and so on. gcloud
automatically comes installed with a default
configuration. This is the configuration whose credentials will be 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.
Read gcloud topic configurations
for
detailed information about using configurations.
Set default properties
The metadata server contains metadata information about a project, including the project ID, project name, and so on. You can query the metadata server to get and use information about the project.
If you specify a default region and zone for your project, then Compute Engine sets these values in the metadata server for your project.
Default regions and zones are set by using the following values:
google-compute-default-zone
google-compute-default-region
To see what your default region and zone settings are, run the following
gcloud
command:
gcloud compute project-info describe --project [PROJECT_ID]
where [PROJECT_ID]
is your project ID.
Look for the following metadata keys and values in the response:
- key: google-compute-default-region
value: ...
- key: google-compute-default-zone
value: ..
If the google-compute-default-region
and google-compute-default-zone
keys and values are missing from the response, that means no default zone or
region is set.
- If no default is set, then
gcloud
prompts you for a region and zone with each request. - If a default is set,
gcloud
automatically uses the default value for all of thegcloud
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
You can change the default zone and region in your metadata server by making a request to the metadata server. 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:
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 gcloud
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
.
export
command to set the zone and region variables.
$ export CLOUDSDK_COMPUTE_ZONE=ZONE
$ export CLOUDSDK_COMPUTE_REGION=REGION
To make these environment variables permanent, include these commands
in your ~/.bashrc
file and restart your terminal.
set
command to set the zone and region variables.
C:\> set CLOUDSDK_COMPUTE_ZONE=ZONE
C:\> set CLOUDSDK_COMPUTE_REGION=REGION
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, it 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 localgcloud
client to these properties when you rungcloud init
. For subsequent requests, the 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 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 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, gcloud
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
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
"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
... metadata: fingerprint: eU448B6JGQw= items: - 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 theinstances 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 theinstances 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 compute
command, 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:
gcloud topic TOPIC
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.
Next steps
That's it, you can now start using the gcloud compute
tool on your own!
Here are some ideas to get you started:
- Follow the quickstart guide for the
gcloud compute
tool. - Review the usage tips.