Creating and Starting a VM Instance

This document explains how to create a virtual machine instance using a boot
disk image, a boot disk snapshot, or a container image. When creating a VM
instance from a boot disk image, you can use either a regular image or a
Shielded VM
image. Shielded VM images offer security features like UEFI-compliant
firmware, Secure Boot, and vTPM-protected Measured Boot.
Compute Engine automatically starts the VM instance after you create
it.

You can create multiple disks for your VM instance during the creation process.
You can also add more disks to the
instance after it is created.

This document explains basic ways to create an instance. For more
specific or complicated instance configurations, see the following resources:

Creating an instance from an image

This section explains how to create an instance from an image of a specific
operating system. A boot disk image contains the
bootloader, boot filesystem, and an operating system that runs on the instance.

For advanced users, you can
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.

To create an instance, specify the image family for the operating system that
you need. Compute Engine offers multiple Linux distributions, some of
which are available as both regular and
Shielded VM images. If you
choose local SSD storage for your instance, you can't use the integrity monitoring
features of Shielded VM, and you can't use the vTPM for shielding data.
For a list of the available image families, see
public images.

Note: You must have access to the public image in order to use it when you
create an instance. By default, you have access to all of the
public images. However, if your project has a defined
list of trusted images,
you can use only the images on that list to create an instance.

The GCP Console adds a network tag to your instance and
creates the corresponding ingress firewall rule that allows all
incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network
tag associates the firewall rule with the instance. For more
information, see Firewall Rules Overview in
the Virtual Private Cloud documentation.

If you want to disable Secure Boot, uncheck Turn on Secure Boot.
Secure Boot helps protect your VM instances against boot-level and
kernel-level malware and rootkits. For more information, see
Secure Boot.

If you want to disable the virtual trusted platform module (vTPM),
uncheck Turn on vTPM. The vTPM enables Measured
Boot, which validates the VM pre-boot and boot integrity. For more
information, see
Virtual Trusted Platform Module (vTPM).

If you want to disable integrity monitoring, uncheck
Turn on Integrity Monitoring. Integrity monitoring lets you
monitor the boot integrity of your
Shielded VM instances using Stackdriver.
For more information, see
Integrity monitoring.

Click the Create button to create and start the instance.

gcloud

Before you create an instance, select an operating system image to use for
the boot disk of your instance.
Use the
gcloud compute images list
command without any flags to see the full list of non-Shielded VM
public images with their image IDs, image families, and image projects:

To use the latest version of an operating system image, specify the
--image-family and --image-project flags. 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.

If you need to use a specific image version instead of the latest version,
specify the --image and --image-project flags. 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.

You can add up to 128 secondary non-boot disks while you are
creating your instance. Specify the --create-disk flag for each
secondary disk you create. To create secondary disks from a public or
stock image, specify the image and image-project properties in the
--create-disk flag. To create a blank disk, do not include these
properties. Optionally, include properties for the disk size and type.

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 use the API client library, you can start a new instance by
directly calling the REST API or using the
instances().insert
method. Here is an example of each option:

REST

In the API, construct a POST request to the instances URI with the same
request body. You can add up to 128 secondary non-boot disks at the
time you create a VM instance by using the initializeParams property for
each additional disk. Create additional disks with a public or a private
image. To add blank disks, do not specify an image source. Optionally, you
can include the diskSizeGb, diskType, and
labels properties.

[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. For blanks disks
do not specify an image source.

[LABEL_KEY] and [LABEL_VALUE] are labels to apply to the disk. The
labels field is optional.

[SIZE_GB] is the disk size.

[DISK_TYPE] is the type of persistent disk, either pd-standard
or pd-ssd.

If you create an instance with blank secondary disks,
format and mount
those disks so that your guest operating system can use them.

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.

Note: You must have access to the custom image to use it when you
create an instance. By default, you have access to all of the custom images
in your project. However, if your project has a defined
list of trusted images,
you can use only the images on that list to create an instance.

The GCP Console adds a network tag to your instance and
creates the corresponding ingress firewall rule that allows all
incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network
tag associates the firewall rule with the instance. For more
information, see Firewall Rules Overview in
the Virtual Private Cloud documentation.

[IMAGE] is an optional field. Use a private or public image. If no
image is specified, the disk will be blank.

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 the most recent, non-deprecated image in the image family.

You can add up to 128 secondary non-boot disks while you are
creating your instance. Specify the --create-disk flag for each
secondary disk you create. To create secondary disks from a public or
stock image, specify the image and image-project properties in the
--create-disk flag. To create a blank disk, do not include these
properties. Optionally, include properties for the disk size and type.

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.

You can create up to 128 secondary non-boot disks at the time you create a
VM instance by using the initializeParams property for each additional disk.
Create additional disks with a public or private image.
To add a blank disk, define the initializeParams entry with no
sourceImage value.

The GCP Console adds a network tag to your instance and
creates the corresponding ingress firewall rule that allows all
incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network
tag associates the firewall rule with the instance. For more
information, see Firewall Rules Overview in
the Virtual Private Cloud documentation.

To add secondary non-boot disks to your VM instance:

Click Management, security, disks, networking, sole tenancy.

Select the Disks tab.

Under Additional disks click Add new disk.

Specify a disk Name, Type, Source type, Mode, and
Deletion rule.

Click Done.

Add additional disks as needed.

Click the Create button to create and start the instance.

gcloud

Create an instance using the
gcloud compute instances create
command, and use the --image and --image-project flag to specify the
image name and the project where the image resides:

You can add up to 128 secondary non-boot disks while you are
creating your instance. Specify the --create-disk flag for each
secondary disk you create. To create secondary disks from a public or
stock image, specify the image and image-project properties in the
--create-disk flag. To create a blank disk, do not include these
properties. Optionally, include properties for the disk size and type.

API

Follow the API instructions to
create an instance from a public image but specify the
image field in the request body. You can add up to 128 secondary non-boot
disks by specifying the initializeParams field for every additional disk.
To add blank disks, do not specify an image source. Optionally, you can
specify the diskSizeGb, diskType, and
labels properties.

The GCP Console adds a network tag to your instance and
creates the corresponding ingress firewall rule that allows all
incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network
tag associates the firewall rule with the instance. For more
information, see Firewall Rules Overview in
the Virtual Private Cloud documentation.

To add secondary non-boot disks to your VM instance:

Click Management, security, disks, networking, sole tenancy.

Select the Disks tab.

Under Additional disks click Add new disk.

Specify a disk Name, Type, Source type, Mode, and
Deletion rule.

Click Done.

Add additional disks as needed.

Click the Create button to create and start 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 boot persistent disk from a snapshot.
Then use that disk to create a new instance.

You can add up to 128 secondary non-boot disks while you are
creating your instance. Specify the --create-disk flag for each
secondary disk you create. To create secondary disks from a public or
stock image, specify the image and image-project properties in the
--create-disk flag. To create a blank disk, do not include these
properties. Optionally, include properties for the disk size and type.

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
boot persistent disk from a snapshot. Then use that disk to create a new
instance.

Restrictions:

Only one persistent disk can be the boot persistent disk.

You must attach the boot 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
boot persistent disk exists already, but the initializeParams
property indicates that Compute Engine should create
a new boot persistent disk.

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. To add up to 128 secondary non-boot disks, use
the initializeParams property for every disk. To add blank disks,
do not include a source image.
Optionally, you can specify the diskSizeGb, diskType, and
labels properties.

Creating an instance from a container image

To deploy and launch a container on a Compute Engine instance, specify
a container image name and optional configuration parameters when you
create the instance. Compute Engine creates the instance using the
latest version of the
Container-Optimized OS public image, which has
Docker installed. Then, Compute Engine launches the container when
the VM starts. See
Deploying Containers on VMs for
more information.

When using a container image from Docker Hub, you must always specify a full
Docker image name. For example, specify the following image name to deploy
an Apache container image: docker.io/httpd:2.4.

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.

compute.subnetworks.use either on the whole project or on the chosen subnet
(VPC networks)

compute.networks.useExternalIp on the project if you need to assign an external
IP address (either ephemeral or static) to the instance using a legacy network

compute.subnetworks.useExternalIp either on the whole project or on the chosen
subnet if you need to assign an external IP address (either ephemeral or static) to the instance
using a VPC network

compute.address.use on the project if specifying a static address in the
project

compute.instances.setMetadata if setting metadata

compute.instances.setTags on the instance if setting tags

compute.instances.setLabels on the instance if setting
labels

compute.images.useReadOnly on the image if creating a new root
persistent disk

compute.disks.create on the project if creating a new root
persistent disk with this instance

compute.disks.useReadOnly on the disk if attaching an existing
persistent disk in read-only mode

compute.disks.use on the disk if attaching an existing disk in
read-write mode

compute.disks.setLabels on the disk if setting
labels

compute.snapshots.create on the project to create a new
snapshot if creating an instance from a snapshot

compute.snapshots.use on the snapshot if creating an instance
from a snapshot

By default, Google Cloud Platform (GCP) creates an auto mode VPC
network called default for each project. If you create
an instance without specifying its network details, Compute Engine uses
the default VPC network and the auto subnet that is in the same region as the
instance.

To use a different network or a subnet that you manually created in an auto mode
or custom mode VPC network, you must specify the subnet when you create the
instance.

The GCP Console adds a network tag to your instance and
creates the corresponding ingress firewall rule that allows all
incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network
tag associates the firewall rule with the instance. For more
information, see Firewall Rules Overview in
the Virtual Private Cloud documentation.

[SUBNET_NAME] is the name of the subnet. The network is inferred from
the specified subnet.

[ZONE_NAME] is the name of the zone where the instance is created,
such as europe-west1-b. The instance's region is inferred from the
zone.

You can add up to 128 secondary non-boot disks while you are
creating your instance. Specify the --create-disk flag for each
secondary disk you create. To create secondary disks from a public or
stock image, specify the image and image-project properties in the
--create-disk flag. To create a blank disk, do not include these
properties. Optionally, include properties for the disk size and type.

API

Follow the API instructions to
create an instance from an image or a
snapshot, but specify the subnet field in the request
body. To add up to 128 secondary non-boot disks, use the initializeParams
property for every disk you create. To add blank disks, do not add a source
image. Optionally, you can specify the diskSizeGb, diskType, and
labels properties.