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)



Instances

An instance is a virtual machine hosted on Google's infrastructure.

Instances can run the Linux images provided by Google, or any customized versions of these images. You can also build and run images of other operating systems.

Google Compute Engine also lets you specify the machine properties of your instances, such as the number of CPUs and the amount of RAM, based on the machine type you use.

Instances are a per-zone resource .

Contents

Overview

At the core of Google Compute Engine is the Instance resource. Every instance is a virtual machine that is customizable and manageable by you; there are few restrictions on how you use your instance

You can perform basic instance configuration and management using either the gcloud compute tool, the Google Developers Console , or the REST API , but to perform any advanced configuration, you must ssh into the instance. By default, all instances support ssh capability for the instance creator, and optionally for other users.

As an instance creator, you have full root privileges on any instances you have started. An instance administrator can also add system users using standard Linux commands.

To start an instance using gcloud compute , use the instances create command. This starts the process of reserving the instance, starting it, and then running any startup scripts that you specify. You can check the status of an instance by running gcloud compute instances describe and looking for a status of RUNNING . Use gcloud compute to add instances to a project and start them, specifying a set of properties for this instance such as desired hardware, image type, zone, and optionally any startup scripts that you want to run. Currently, adding and removing an instance is the same as starting and stopping an instance; you cannot add an instance to a project without starting it, or remove it without stopping it.

A project holds one or more instances but an instance can be a member of one and only one project. When you start an instance, you must specify which project and zone it should belong to. When you stop an instance, it is removed from the project. Project information can be viewed using the gcloud compute project-info describe command, but you must use the Google Developers Console to create and manage projects.

Instances can communicate with other instances in the same network and with the rest of the world through the Internet. A Network object is restricted to a single project, and cannot communicate with other Network objects. See Networks and Instances for more information about network communication to and from an instance.

Useful gcloud compute commands:

Creating and starting an instance

An instance is created and started in a single step. Google Compute Engine does not currently allow you add an instance to a project without starting it. An instance takes a few moments to start up. You must check the instance status to learn when it is actually running. See Checking Instance Status for more information.

Each instance must have a root persistent disk that stores the instance's root filesystem. It is possible to create this root persistent disk when you create your instance, or create it separately and attach it to the instance.

Start an instance using gcloud compute

To start an instance using gcloud compute instances create command. 

 $ gcloud compute instances create example-instance \
          --zone us-central1-a \
          --machine-type n1-standard-1 \
          --image debian-7-backports

 Created [https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/example-instance].
 NAME              ZONE          MACHINE_TYPE  INTERNAL_IP   EXTERNAL_IP    STATUS
 example-instance  us-central1-a n1-standard-1 10.105.155.92 173.255.114.53 RUNNING

The command creates a virtual machine with the follow default settings:

Starting an instance in the API

To start an instance in the API, construct a request with a source image: 

body = {
  'name': <instance-name>,
  'machineType': <fully-qualified-machine-type-url>
  'networkInterfaces': [{
    'accessConfigs': [{
      'type': 'ONE_TO_ONE_NAT',
      'name': 'External NAT'
     }],
    'network': <fully-qualified-network-url>
  }],
  'disks': [{
     'autoDelete': 'true',
     'boot': 'true',
     'type': 'PERSISTENT',
     'initializeParams': {
        'diskName': 'my-root-disk',
        'sourceImage': <fully-qualified-image-url>,
        'diskType': 'https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/diskTypes/pd-standard'
     }
   }]
}

By providing the following in your request: 

'disks': [{
   'autoDelete': 'true',
   'boot': 'true',
   'type': 'PERSISTENT',
   'initializeParams': {
      'diskName': 'my-root-disk',
      'sourceImage': <fully-qualified-image-url>,
      'diskType': 'https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/diskTypes/pd-standard'
    }
}]

Compute Engine also creates a root persistent disk with the source image you indicated. You can only provide initalizeParams for a root persistent disk, and can only provide it once per instance creation request. Note that the autoDelete flag also indicates to Compute Engine that the root persistent disk should be automatically deleted when the instance is deleted.

When you are using the API to specify a root persistent disk:

If you're using the API client library, you can start a new instance using the instances().insert function. Here is a snippet from the Python client library: 

def addInstance(auth_http, gce_service):
# Construct the request body
 body = {
  'name': NEW_INSTANCE_NAME,
  'machineType': <fully-qualified-machine_type_url>,
  'networkInterfaces': [{
    'accessConfigs': [{
      'type': 'ONE_TO_ONE_NAT',
      'name': 'External NAT'
     }],
    'network': <fully-qualified-network_url>
  }],
  'disks': [{
     'autoDelete': 'true',
     'boot': 'true',
     'type': 'PERSISTENT',
     'initializeParams' :{
        'diskName': 'my-root-disk',
        'sourceImage': <fully-qualified-image-url>,
        'diskType': 'https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/diskTypes/pd-standard'
     }
  }]
}

# Create the instance
request = gce_service.instances().insert(
     project=PROJECT_ID, body=body, zone=DEFAULT_ZONE)
response = request.execute(auth_http)
response = _blocking_call(gce_service, auth_http, response)

print response

You could also make a request to the API directly by sending a POST request to the instances URI with the same request body: 

def addInstance(http, listOfHeaders):
  url = 'https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances'

  body = {
    'name': NEW_INSTANCE_NAME,
    'machineType': <fully-qualified-machine_type_url>,
    'networkInterfaces': [{
      'accessConfigs': [{
        'type': 'ONE_TO_ONE_NAT',
        'name': 'External NAT'
       }],
      'network': <fully-qualified-network_url>
    }],
    'disks': [{
       'autoDelete': 'true',
       'boot': 'true',
       'type': 'PERSISTENT',
       'initializeParams': {
          'diskName': 'my-root-disk',
          'sourceImage': <fully-qualified-image-url>,
          'diskType': 'https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/diskTypes/pd-standard'
       }
     }]

  bodyContentURLEncoded = urllib.urlencode(bodyContent)
  resp, content = http.request(uri=url, method="POST", body=dumps(bodyContent), headers=listOfHeaders)

  print resp
  print content

Checking instance status

When you first create an instance, you should check the instance status to see if it is running before you can expect it to respond to requests. It can take a couple seconds before your instance is fully up and running after the initial instances create request. You can also check the status of an instance at anytime after instance creation.

To check the status of an instance, call [ gcloud compute instances list ] or gcloud compute instances describe INSTANCE .

Instances are marked with the following states:

Example 

$ gcloud compute instances describe example-instance
...
canIpForward: false
creationTimestamp: '2014-07-29T10:55:57.766-07:00'
disks:
- autoDelete: true
  boot: true
  deviceName: persistent-disk-0
  index: 0
  kind: compute#attachedDisk
  mode: READ_WRITE
  source: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/disks/example-disk
  type: PERSISTENT
id: '18184921949557497761'
kind: compute#instance
machineType: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/machineTypes/n1-standard-1
metadata:
  fingerprint: NR_Gy3Hxzus=
  kind: compute#metadata
name: example-instance
networkInterfaces:
- accessConfigs:
  - kind: compute#accessConfig
    name: external-nat
    natIP: 173.255.114.53
    type: ONE_TO_ONE_NAT
  name: nic0
  network: https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default
  networkIP: 10.105.155.92
scheduling:
  automaticRestart: true
  onHostMaintenance: MIGRATE
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/example-instance
serviceAccounts:
- email: [email protected]
  scopes:
  - https://www.googleapis.com/auth/devstorage.read_only
status: RUNNING
tags:
  fingerprint: 42WmSpB8rSM=
zone: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

Connecting to an instance using ssh

By default, you can always connect to an instance using ssh. This is useful so you can manage and configure your instances beyond the basic configuration enabled by gcloud compute or the REST API. The easiest way to ssh into an instance is to use the gcloud compute ssh command from your local computer. For example, the following command connects to an instance named example-instance: 

$ gcloud compute ssh example-instance

You can use ssh directly without using the gcloud compute wrapper, as described in Using standard ssh .

Setting up your ssh keys

Every time you run gcloud compute ssh , gcloud compute checks for ssh key files in the locations listed below. If there are no existing key files, gcloud compute will generate a new ssh key: 

$ gcloud compute ssh example-instance
WARNING: You do not have an SSH key for Google Compute Engine.
WARNING: [/usr/bin/ssh-keygen] will be executed to generate a key.
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):

You are not required to provide a passphrase but if you don't, the keys on your local machine will be unencrypted. We recommend providing a passphrase to encrypt your keys.

The newly-generated ssh keys are stored in the following locations:

gcloud compute copies your public key to the project metadata which allows the virtual machine to see the new key. If you want to use existing keys that are stored in a different location, specify the file using the --ssh-key-file flag.

If you want, you can specify multiple keys for a virtual machine instance using the gcloud compute project-info add-metadata command with the sshKeys metadata key: 

$ echo user1:$(cat ~/.ssh/key1.pub) > /tmp/a
$ echo user2:$(cat ~/.ssh/key2.pub) >> /tmp/a
$ gcloud compute project-info add-metadata example-instance --metadata-from-file sshKeys=/tmp/a

You can also add ssh keys through the Google Developers Console. See Setting up ssh keys for more information.

Being able to add multiple keys is useful for adding multiple users to an instance at startup time, but it also limits the set of ssh keys to be exactly those you specified.

That's it! You have set up ssh access to your instances. Note that this process sets up ssh keys for your local computer, but if you want to ssh in from more than one computer, you should read Connecting from different clients .

Connecting using standard ssh

You can use standard ssh rather than gcloud compute ssh with the following syntax: 

ssh -i KEY_FILE -o UserKnownHostsFile=/dev/null -o CheckHostIP=no -o StrictHostKeyChecking=no USER@IP_ADDRESS

Important Flags and Parameters:

KEY_FILE
[ Required ] The file where the keys are stored on the computer e.g. ~/.ssh/google_compute_engine
USER
[ Required ] The username to log in that instance. Typically, this is the username of the local user running gcloud compute .
IP_ADDRESS
[ Required ] The external IP address of the instance.

Connecting from the browser (Open Preview)

You can also ssh into an instance directly from your web browser in the Google Developers Console . This feature is in Open Preview, which means that it is subject to change and is not covered by any SLA or deprecation policy.

Connecting from one instance to another

If your instance doesn't have an externally-visible IP address, you can still ssh into it by connecting to an instance on the network with an external address, then from there, connect to the internal-only instance from your externally-visible instance. You might need to do this if you've started an instance without an external IP address either intentionally or by accident.

To ssh from one instance to another:

  1. Start ssh-agent using the following command to manage your keys for you: 

    $ eval ssh-agent

  2. Call ssh-add to load the gcloud compute keys from your local computer into the agent, and use them for all ssh commands for authentication: 

    $ ssh-add ~/.ssh/google_compute_engine

  3. Log into an instance with an external IP address: 

    $ gcloud compute ssh INSTANCE

  4. From this externally-addressable instance, you can now log into any other instance on the same network by calling gcloud compute ssh INSTANCE .

  5. When you are done, call exit repeatedly to log out of each instance in turn.
  6. You can continue to simply ssh into your internal instances through your external instance until you close your command window, which will close the ssh-agent context.

Example 

me@local:~$ eval ssh-agent
Agent pid 17666

me@local:~$ ssh-add ~/.ssh/google_compute_engine
Identity added: /home/user/.ssh/google_compute_engine (/home/user/.ssh/google_compute_engine)

me@local:~$ gcloud compute ssh myinst
INFO: Running command line: ssh -o UserKnownHostsFile=/dev/null -o CheckHostIP=no -o StrictHostKeyChecking=no -i /home/user/.ssh/google_compute_engine -o LogLevel=QUIET -A -p 22 [email protected] --
Linux myinst 2.6.39-gcg-yyyymmdd1612 #18 SMP .... x86_64 GNU/Linux
....
me@myinst:~$ ssh myinst2
....
1 package can be updated.
0 updates are security updates.
me@myinst2:~$ exit
logout
Connection to myinst2 closed.
me@myinst:~$

Root access and instance administrators

For security reasons, the standard Google images do not provide the ability to ssh in directly as root. The instance creator and any users that were added using the metadata sshKeys value are automatically administrators to the account, with the ability to run sudo without requiring a password.

Although it is not recommended, advanced users can modify /etc/ssh/sshd_config and restart sshd to change this policy.

Setting instance scheduling options

By default, Google Compute Engine automatically manages the scheduling decisions for your instances. For example, if your instance is terminated due to a system or hardware failure, Compute Engine automatically restarts that instance. Instance scheduling options let you change this automatic behavior.

Maintenance behavior

Persistent disks are preserved in both migrate or terminate cases. For the terminate and reboot case, your persistent disk will be briefly detached from the instance while it is being rebooted, and then reattached once the instance is restarted.

See How to Set Scheduling Options below for the default maintenance behavior values and also how to change this setting on existing instances.

Automatic restart

You can set up Google Compute Engine to automatically restart an instance if it is taken offline by a system event, such as a hardware failure or scheduled maintenance event, using the automaticRestart setting. This setting does not apply if the instance is taken offline through a user action, such as calling sudo shutdown .

When Google Compute Engine automatically restarts your instance, it reports a system event that is published to the list of zone operations. You can review this event by performing a gcloud compute operations list --zones ZONE request or by viewing the list of operations in the Google Developers Console , or through an API request. The event will appear with the following text: 

compute.instances.automaticRestart

How to set scheduling options

All instances are configured with default values for onHostMaintenance and automaticRestart settings. The default setting for instances is to set the onHostMaintenance flag to migrate , in which case Google Compute Engine will migrate the instance around scheduled maintenance events.

If you want to manually set scheduling options of an instance, you can do so when first creating the instance or after the instance is created , using the setScheduling method.

Specifying scheduling options during instance creation

To specify the maintenance behavior and automatic restart settings of a new instance in gcloud compute , use the --maintenance-policy flag. By default, instances are automatically set to restart unless indicated by the --no-restart-on-failure flag. 

 $ gcloud compute instances create INSTANCE .. [--maintenance-policy MAINTENANCE_POLICY] [--no-restart-on-failure]

In the API, make a POST request to: 

 https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances

with the onHostMaintenance and automaticRestart parameters as part of the request body: 

{
  "kind": "compute#instance",
  "name": "example-instance",
  "description": "Front-end for real-time ingest; don't migrate.",
...
  // User options for influencing this Instance’s life cycle.
  "scheduling": {
    "onHostMaintenance": "migrate",
    "automaticRestart": "true" # specifies that Google Compute Engine should automatically restart your instance
  }
}

For more information, see the Instances reference documentation.

Updating scheduling options for an existing instance

To update the scheduling options of an instance, use the instances set-scheduling subcommmand command with the same parameters and flags used in the instance creation command above: 

$ gcloud compute instances set-scheduling INSTANCE [--maintenance-policy BEHAVIOR] [--no-restart-on-failure | --restart-on-failure]

In the API, you can make a request to the following URL: 

https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances/setScheduling

The body of your request must contain the new value for the scheduling options: 

{
  "onHostMaintenance": "migrate"
  "automaticRestart": "true" # specifies that Google Compute Engine should automatically restart your instance
}

For more information, see the instances : setScheduling reference documentation.

Installing packages and configuring an instance

The instance creator has administrator privileges on any instance she adds to a project, and is automatically on the SUDO list.

When you are logged into an instance as the administrator, you can install packages and configure the instance the same way you would a normal Linux box. For example, you can install Apache, as shown here: 

user@myinst:~$ sudo apt-get update
user@myinst:~$ sudo apt-get install apache2
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following extra packages will be installed:
[...]

You can move files between your local computer and instance using gcloud compute copy-files as described in Copying files between an instance and local computer .

Note that your machine needs access to the Internet to be able to run apt-get. This means that it needs either an external IP address , or access to an Internet proxy .

It is possible to detect when a maintenance event is about to happen through an instance's virtual machine metadata server. A special metadata attribute, maintenance-event will update its value shortly before the started and again at the end of a maintenance event, allowing you to detect when a scheduled maintenance event is going to happen and when it ends. You can use this information to help automate any scripts or commands you may want to run at those times.

For more information, see the Scheduled maintenance notice section on the Metadata server documentation.

Copying files between an instance and local computer

Use gcloud compute copy-files to transfer files between your instance and local computer. To copy files from your instance to your local computer: 

$ gcloud compute copy-files my-instance-:~/file-1 \
         my-instance:~/file-2 \
         ~/local-dir \
         --zone ZONE \

To copy files from your local machine to your instance: 

$ gcloud compute copy-files ~/local-dir/file-1 \
         my-instance:~/remote-destination \
         --zone ZONE

Detecting if you are running in Google Compute Engine

It is common for systems to want to detect if they are running within a specific cloud environment. Use the following isntructions to help you detect if you are running in Compute Engine.

Linux


For Linux virtual machines, you can query for the metadata server for a specific header that indicates you are running within Compute Engine. For more information, see Detecting if you are running in Compute Engine .

For Linux images v20131120 and newer, you can request more explicit confirmation using the dmidecode tool. The dmidecode tool can be used to access the DMI/SMBIOS information in /proc/mem directly. Run the following command and the dmidecode tool should print out "Google" to indicate that you are running in Google Compute Engine: 

my@myinst:~$ sudo dmidecode -s bios-vendor | grep Google
Google

Windows


On Windows instances, "Google" is listed as the system manufacturer and model. You can use utilities like msinfo32.exe to look up this information. For example, msinfo32 displays the following information:

msinfo32 screen displaying Google as manufacturer and model

If you need to programmatically determine this information on a Windows instance, you can create a Windows Management Instrumentation (WMI) application with some modifications .

Enabling network traffic

By default, all new instances have the following connections enabled:

Any other incoming traffic to an instance is blocked. You must explicitly assign new firewall rules a network to enable other connections. See Connecting to an instance using ssh to learn how to ssh into your instance, or Networks and Firewalls to learn how instances communicate with each other over IP, and how to set up an externally accessible HTTP connection to an instance.

Using instance tags

You can assign tags to your instances to help coordinate or group instances that may share common traits or attributes. For example, if there are several instances that perform the same task, such as serving a large website, you may consider tagging these instances with a shared word or term. Instance tags are also used by networks and firewalls to identify which instances firewall rules may apply to. Tags are also reflected in the metadata server, so you can use them for applications running on your instances.

To assign tags to a running instance using gcloud compute , use the instances add-tags command: 

$ gcloud compute instances add-tags INSTANCE --tags tag-1 tag-2

Restart an instance

It is possible to restart or reset your instance in multiple ways.

You can perform a soft reset on an instance by using the instances reset command or by making a POST request to the following URI: 

https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances/<instance-name>/reset

Performing a reset on your instance is similar to pressing the reset button on your computer, which clears the memory and resets the virtual machines to its initial state. Note that your instance remains in RUNNING mode through the reset.

To reset your instance using gcloud compute : 

$ gcloud compute instances reset INSTANCE

To reset your instance using the client libraries, construct a request to the instances().reset method: 

def resetInstance(auth_http, gce_service):
  request = gce_service.instances().reset(project=PROJECT_ID, zone=ZONE_NAME, instance=INSTANCE_NAME)
  response = request.execute(auth_http)

  print response

For more information on this method, see the instances().reset reference documentation.

You can also choose to reset your instance using the following methods as well:

Shutting down an instance

When you shut down an instance, the following things will happen:

There are two ways to shut down an instance:

Listing all running instances

You can see a list of all instances in a project by calling instances list : 

$ gcloud compute instances list
NAME               ZONE          MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP     STATUS
example-instance   us-central1-a n1-standard-1 10.105.155.92  173.255.114.53  RUNNING
example-instance-2 us-central1-a n1-standard-1 10.181.215.203 146.148.32.59   RUNNING

By default, gcloud compute provides an aggregate listing of all your resources across all available zones. If you want a list of resources from just a single zone, provide the --zones flag in your request.

In the API, you need to make requests to two different methods to get a list of aggregate resources or a list of resources within a zone. To make a request for an aggregate list, make a GET request to that resource's aggregatedList URI: 

https://www.googleapis.com/compute/v1/aggregated/instances

In the client libraries, make a request to the instances().aggregatedList function: 

def listAllInstances(auth_http, gce_service):
  request = gce_service.instances().aggregatedList(project=PROJECT_ID)
  response = request.execute(auth_http)

  print response

To make a request for a list of instances within a zone, make a GET request to the following URI: 

http://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/instances

In the API client libraries, make a instances().list request: 

def listInstances(auth_http, gce_service):
  request = gce_service.instances().list(project=PROJECT_ID,
    zone='<zone>')
  response = request.execute(auth_http)

  print response

Handling instance failures

Unfortunately, individual instances will experience failures from time to time. This can be due to a variety of reasons, including scheduled maintenance, scheduled zone outages (in zones that do not yet support transparent maintenance), unexpected outages, hardware error, or other system failures. As a way to mitigate such situations, you should use persistent disks and back up your data routinely.

If an instance fails, it will be restarted automatically, with the same root persistent disk, metadata, and instance settings as when it failed. To control the automatic restart behavior for an instance, see How to set scheduling options . However, if an instance is terminated for a zone maintenance window it will stay terminated and will not be restarted when the zone exits the maintenance window.

In general, you should design your system to be robust enough that the failure of a single instance should not be catastrophic to your application. For more information, see Designing Robust Systems .

Creating a custom image

You can create a custom instance image by customizing a provided image, and then load it onto new instances as they are brought up. See Creating an image from a root persistent disk for more information.

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.