Creating and Starting an Instance

This document explains how to create a virtual machine instance using an image or a snapshot. Compute Engine automatically starts the instance for you after you create it.

The process for creating Windows Server and SQL Server instances is different. See Creating Windows Server Instances and Creating SQL Server Instances.

Before you begin

Creating an instance from an image

This section explains how to create an instance from an image of a specific operating system. An image contains the root filesystem and OS that will run on the instance. To learn more about the available operating system images, read the Images documentation.

For advanced users, you can also create a custom image to use in place of the public images offered by Compute Engine.

You can create an instance with an image in the Google Cloud Platform Console, the gcloud command-line tool, or the API.

Creating an instance from a public image

Public images are provided and maintained by Google, open-source communities, and third-party vendors. By default, all projects have access to these images and can use them to create instances with common operating system images.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Select your project and click Continue.
  3. Click the Create instance button.
  4. In the Boot disk section, click Change to begin configuring your boot disk.
  5. In the OS images tab, choose an image.
  6. Click Select.
  7. If desired, change the zone for this instance.

    Note: When choosing a zone in the Cloud Platform Console, the list of zones is randomized within each region. This is intended to encourage use across multiple zones.

  8. Click the Create button to create and start the instance.

gcloud

Before you start an instance, select an operating system image to use for the root disk on your instance. Use the gcloud compute images list command to see the full list of public images with their image IDs, image families, and image projects:

gcloud compute images list

After you select an image, start an instance using the gcloud compute instances create command.

To use the latest version of an operating system image, provide the --image-family flag and the --image-project flag. For example, debian-9 is an image family that returns the most recent version of the Debian 9 image that is not deprecated and debian-cloud is the image project.

Start an instance with the latest image from an image family:

gcloud compute instances create [INSTANCE_NAME] \
    --image-family [IMAGE_FAMILY] \
    --image-project [IMAGE_PROJECT]

where:

If the command is successful, the tool responds with the properties of the new instance:

Created [https://www.googleapis.com/compute/v1/projects/myproject/zones/[ZONE]/instances/[INSTANCE_NAME]].
NAME            ZONE   MACHINE_TYPE  INTERNAL_IP   EXTERNAL_IP    STATUS
[INSTANCE_NAME] [ZONE] n1-standard-1 10.105.155.92 173.255.114.53 RUNNING

If you need to use a specific image version instead of the latest version, specify the --image flag and the image project with the --image-project flag. For example, to create an instance that uses the debian-9-stretch-v20170619 Debian image, specify --image debian-9-stretch-v20170619 and --image-project debian-cloud.

Start an instance with a specific version of an image:

gcloud compute instances create [INSTANCE_NAME] \
    --image [IMAGE_ID] \
    --image-project [IMAGE_PROJECT]

where:

  • [INSTANCE_NAME] is the name for the new instance.
  • [IMAGE_ID] is a specific image.
  • [IMAGE_PROJECT] is the image project that the image belongs to.

API

To start an instance in the API, send a request with a:

  • Source image
  • Network interface
  • Machine type
  • If your VPC network is a custom mode VPC network, you must also specify the subnet where you want the instance to be created.

After you decide on your resource properties, create a request body and make your API request. To learn more about constructing API requests and handling API responses, read the Creating API Requests and Handling Responses documentation.

Making the API request

If you're using the API client library, you can start a new instance using the instances().insert or directly calling the REST API. Here are some snippets of both ways.

Python Client Library

def create_instance(compute, project, zone, name, bucket):
    # Get the latest Debian Jessie image.
    image_response = compute.images().getFromFamily(
        project='debian-cloud', family='debian-8').execute()
    source_disk_image = image_response['selfLink']

    # Configure the machine
    machine_type = "zones/%s/machineTypes/n1-standard-1" % zone
    startup_script = open(
        os.path.join(
            os.path.dirname(__file__), 'startup-script.sh'), 'r').read()
    image_url = "http://storage.googleapis.com/gce-demo-input/photo.jpg"
    image_caption = "Ready for dessert?"

    config = {
        'name': name,
        'machineType': machine_type,

        # Specify the boot disk and the image to use as a source.
        'disks': [
            {
                'boot': True,
                'autoDelete': True,
                'initializeParams': {
                    'sourceImage': source_disk_image,
                }
            }
        ],

        # Specify a network interface with NAT to access the public
        # internet.
        'networkInterfaces': [{
            'network': 'global/networks/default',
            'accessConfigs': [
                {'type': 'ONE_TO_ONE_NAT', 'name': 'External NAT'}
            ]
        }],

        # Allow the instance to access cloud storage and logging.
        'serviceAccounts': [{
            'email': 'default',
            'scopes': [
                'https://www.googleapis.com/auth/devstorage.read_write',
                'https://www.googleapis.com/auth/logging.write'
            ]
        }],

        # Metadata is readable from the instance and allows you to
        # pass configuration from deployment scripts to instances.
        'metadata': {
            'items': [{
                # Startup script is automatically executed by the
                # instance upon startup.
                'key': 'startup-script',
                'value': startup_script
            }, {
                'key': 'url',
                'value': image_url
            }, {
                'key': 'text',
                'value': image_caption
            }, {
                'key': 'bucket',
                'value': bucket
            }]
        }
    }

    return compute.instances().insert(
        project=project,
        zone=zone,
        body=config).execute()

REST

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": "[INSTANCE_NAME]",
    "machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
    "networkInterfaces": [{
      "accessConfigs": [{
        "type": "ONE_TO_ONE_NAT",
        "name": "External NAT"
       }],
      "network": "global/networks/default"
    }],
    "disks": [{
       "autoDelete": "true",
       "boot": "true",
       "type": "PERSISTENT",
       "initializeParams": {
          "sourceImage": "projects/[IMAGE_PROJECT]/global/images/family/[IMAGE]"

       }
     }]

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

  print resp
  print content

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [PROJECT_ID] is your project ID.
  • [ZONE] is the zone for this instance.
  • [MACHINE_TYPE] is the machine type of the instance.
  • [IMAGE_PROJECT] is the image project that the image belongs to, such as debian-cloud, ubuntu-os-cloud, and so on.
  • [IMAGE] is one of the available public image families. For example, family/debian-9 uses the latest version of the Debian 9 image. Alternatively, you can use a specific image version such as debian-9-stretch-v20170619 without the family/ path.

Creating an instance from a custom image

A custom image belongs only to your project. To create an instance with a custom image, you must first have a custom image. To learn how to create a custom image, read Creating a Custom Image.

Console

  1. Go to the VM instances page.

    Go to the VM Instances page

  2. Select your project and click Continue.
  3. Click the Create instance button.
  4. In the Boot disk section, click Change to begin configuring your boot disk.
  5. Select the Custom Images tab.
  6. Make sure your project is selected in the dropdown menu.
  7. Choose the image you want and click the Select button.
  8. If desired, change the zone for this instance.

    Note: When choosing a zone in the Cloud Platform Console, the list of zones is randomized within each region. This is intended to encourage use across multiple zones.

  9. Continue creating your instance.

gcloud

Using the gcloud command-line tool, run:

 gcloud compute instances create [EXAMPLE_INSTANCE] --image [IMAGE_NAME]

where:

  • [EXAMPLE_INSTANCE] is the instance name.
  • [IMAGE_NAME] is the name of the image.

If you created your custom images as part of an image family, specify that image family instead of the image name. By doing so, the instance automatically uses most recent, non-deprecated image in the image family.

API

The process for creating an instance with a custom image in the API is the same as if you were creating an instance with a publicly-available image. In the sourceImage URI, provide your own project ID and the image name:

 ...
 "initializeParams" :{
    "sourceImage": "global/images/[IMAGE_NAME]"
 }
 ...

where:

+ `[PROJECT_ID]` is your project ID.
+ `[IMAGE_NAME]` is the specific image such as
  `debian-9-stretch-v20170619`. Alternatively, you can specify an image
  family. For example, `family/debian-9` returns the latest version of
  the Debian 9 image.

Creating an instance with an image shared with you

If another user has shared an image with you, you can use the image to create a new instance.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Select your project and click Continue.
  3. Click the Create instance button.
  4. In the Boot disk section, click Change to begin configuring your boot disk.
  5. Select the Custom Images tab.
  6. Select the image project from the dropdown.
  7. Choose the image you want and click the Select button.
  8. If desired, change the zone for this instance.

    Note: When choosing a zone in the Cloud Platform Console, the list of zones is randomized within each region. This is intended to encourage use across multiple zones.

  9. Continue creating your instance.

gcloud

Start an instance using the --image and --image-project flag, specifying the image name and the project where the image lives:

gcloud compute instances create [INSTANCE_NAME] \
    --image [IMAGE] \
    --image-project [IMAGE_PROJECT]

where:

  • [INSTANCE_NAME] is the name for the new instance.
  • [IMAGE] is the name of the image.
  • [IMAGE_PROJECT] is the project that the image belongs to.

If the command is successful, gcloud responds with the properties of the new instance:

Created [https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-b/instances/example-instance].
NAME                 ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
example-instance     us-central1-b  n1-standard-1               10.240.0.4   104.198.53.60  RUNNING

API

Follow the API instructions to create an instance from a public image but specify the image field in the request body using this format:

...
image: "projects/[PROJECT_ID]/global/images/[IMAGE]
...

where:

  • [PROJECT_ID] is the project containing the image.
  • [IMAGE] is the name of the specific image.

Creating an instance from a snapshot

If you backed up a root persistent disk with a snapshot, you can use that snapshot to create a new instance. Creating an instance from a snapshot is useful when you need to roll an instance back to a previous state or restore the root disk of an instance that you deleted unintentionally.

Console

  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

  2. Click the Create instance button.
  3. On the Create a new instance page, fill in the desired properties for your instance.
  4. In the Boot disk section, click Change.
  5. Click the Snapshots tab and choose a snapshot from the list.
  6. Click Select.
  7. If desired, change the zone for this instance.

    Note: When choosing a zone in the Cloud Platform Console, the list of zones is randomized within each region. This is intended to encourage use across multiple zones.

  8. Fill in the rest of your desired properties.
  9. Click the Create button to create the instance.

gcloud

Using the gcloud command-line tool, you cannot use a snapshot to directly create an instance the same way that you can in the console. First, create a new standalone root persistent disk from a snapshot. Then use that disk to create a new instance.

  1. Create a standalone root persistent disk from a snapshot.

    gcloud compute disks create [DISK_NAME] --source-snapshot [SNAPSHOT_NAME]
    
  2. Attach the disk with the boot=yes property when you create a new instance.

    gcloud compute instances create [INSTANCE_NAME] \
        --disk name=[DISK_NAME],boot=yes
    

API

In the API, you cannot use a snapshot to directly create an instance the same way that you can in the console. First, create a new standalone root persistent disk from a snapshot. Then use that disk to create a new instance.

Restrictions:

  • Only one persistent disk can be the root persistent disk.
  • You must attach the root persistent disk as the first disk for that instance.
  • If you specify the source property, you cannot also specify the initializeParams property. Providing a source indicates that the root persistent disk exists already, but the initializeParams property indicates that Compute Engine should create a new root persistent disk.

To create an instance from a snapshot:

  1. Create a standalone root persistent disk from a snapshot.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/disks
    
    {
      "name": "[DISK_NAME]",
      "sourceSnapshot": "zones/[ZONE]/snapshots/[SNAPSHOT_NAME]"
    }
    
  2. Attach the disk when you create a new instance. In the request body include the properties to create a new instance. In the disks property, include the source field with a URL to the persistent disk that you want to attach:

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances
    
    {
      "name": "[INSTANCE_NAME]",
      "machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]"
      "networkInterfaces": [{
        "accessConfigs": [{
          "type": "ONE_TO_ONE_NAT",
          "name": "External NAT"
         }],
        "network": "global/networks/default"
      }],
      "disks": [{
         "source": "zones/[ZONE]/disks/[DISK_NAME]",
         "boot": true
       }]
    }
    

Creating an instance with access to other Google Cloud Platform Services

If you plan to run an application on your virtual machine instance that needs access to other Google Cloud Platform services, create a service account before creating the instance, and then follow the instructions to set up an instance to run as a service account. A service account is a special account whose credentials you can use in your application code to access other Google Cloud Platform services.

For more information on service accounts, read the Service Accounts Overview.

Creating an instance in a custom mode VPC network

By default, Compute Engine creates auto mode VPC networks for Cloud Platform Console projects. With auto mode VPC networks, Compute Engine infers the subnet of the instance automatically from the zone so you don't need to explicitly provide a network specification when creating instances.

However, if your network is a custom mode VPC network, you must specify the subnet manually when you create an instance.

Console

  1. Go to the VM instances page.

    Go to the VM Instances page

  2. Select your project and click Continue.
  3. Click the Create instance button.
  4. Expand the Management, disk, networking, SSH keys section.
  5. On the VPC network tab, select a custom mode VPC network from the VPC network drop down.
  6. If desired, change the zone for this instance.

    Note: When choosing a zone in the Cloud Platform Console, the list of zones is randomized within each region. This is intended to encourage use across multiple zones.

  7. Click the Create button to create and start the instance.

gcloud

Using the gcloud command-line tool, follow the same instructions to create an instance from an image or a snapshot, and add the --subnet [SUBNET_NAME] flag:

gcloud compute instances create [INSTANCE_NAME] --subnet [SUBNET_NAME]

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [SUBNET_NAME] is the name of the subnet.

API

Follow the API instructions to create an instance from an image or a snapshot, but specify the subnet field in the request body:

    ...
    "networkInterfaces": [
    {
      "network": "global/networks/[NETWORK_NAME]",
      "subnetwork": "regions/[REGION]/subnetworks/[SUBNET_NAME]",
      "accessConfigs": [
        {
          "name": "External NAT",
          "type": "ONE_TO_ONE_NAT"
        }
      ]
     }
    ]...

What's next?

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Compute Engine Documentation