Create VM instances from machine images

After you create a machine image, you can use it to make copies of the source VM instance. For more information about the uses of machine images, see when to use a machine image.

A machine image contains most of the information and data needed for cloning an instance.

A machine image is unchangeable. However, you can override almost all the properties of the machine image when creating an instance from the machine image.

You can create instances from machine images using either the Google Cloud console, the Google Cloud CLI, or REST.

Before you begin

If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Restrictions

The following restrictions apply when you create VMs from machine images:

You can create at most 6 VMs from a source machine image in 60 minutes. If you exceed this limit, the instance create operation fails and returns an error similar to the following:
```
Operation rate exceeded for resource 'projects/test/global/machineImages/machine-image-1'.
Too frequent operations from the source resource.
```
To create more VMs than the defined limit (6 VMs in 60 minutes), create additional machine images from the source VM or create short-lived machine images from the new VMs. You can then create the required number of VMs from the new machine images.
You cannot create VMs from machine images with attached regional persistent disks using the Google Cloud console. Use the Google Cloud CLI or REST and specify the replicaZones and deviceName parameters for each attached regional persistent disk. For more information, see Create a VM from a machine image with property overrides.

Create a VM from a machine image (no override)

Permissions required for this task

To perform this task, you must have the following permissions:

compute.instances.create on the project
compute.machineImages.useReadOnly on the machine image you want to use
Any additional permissions needed to set attributes on the instance, for example, the setTags permission

If you want to create a VM that is fully based on the machine image with no changes to the properties, use this method.

Console

In the Google Cloud console, go to the Create an instance page.

Go to Create an instance
Click New VM instance from machine image.
Select your machine image and click Continue.
Optional: Customize the VM details.
Click Create.

gcloud

Use the gcloud compute instances create command to create an instance from a machine image.

gcloud compute instances create VM_NAME \
    --zone=ZONE \
    --source-machine-image=SOURCE_MACHINE_IMAGE_NAME

Replace the following:

VM_NAME: the name of the VM to create.
ZONE: the zone for the VM.
SOURCE_MACHINE_IMAGE_NAME: the machine image to create the VM from.

Example

For example, you can use the following gcloud command to create a VM called my-instance in the us-east1-b zone, from a machine image called my-machine-image.

gcloud compute instances create my-instance \
    --zone=us-east1-b \
    --source-machine-image=my-machine-image

After the VM is created, the output resembles the following:

Created [https://www.googleapis.com/compute/v1/projects/project-12345/zones/us-east1-b/instances/my-instance].
NAME               ZONE        MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP   STATUS
my-instance        us-east1-b  e2-standard-2               192.0.2.1   203.224.0.113  RUNNING

REST

In the API, construct a POST request to the instances.insert method. In the request body, include the following parameters:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "sourceMachineImage": "SOURCE_MACHINE_IMAGE_URL"
}

Replace the following:

PROJECT_ID: your project ID.
ZONE: the zone for the VM.
VM_NAME: the name of the VM to create.
SOURCE_MACHINE_IMAGE_URL: the full or partial URL of the machine image that you want to use to create the VM. For example, if you have a machine image called my-machine-image in a project called myProject. The following URLs are valid:
- https://www.googleapis.com/compute/v1/projects/myProject/global/machineImages/my-machine-image
- projects/myProject/global/machineImages/my-machine-image
- global/machineImages/my-machine-image

Create a VM from a machine image with property overrides

Permissions required for this task

To perform this task, you must have the following permissions:

compute.instances.create on the project
compute.machineImages.useReadOnly on the machine image you want to use
Any additional permissions needed to set attributes on the instance, for example, the setTags permission

If you want to create a VM primarily based on the machine image but with a few changes, you can use the override behavior. To use the override behavior, you pass in attributes to override existing machine image properties when creating the instance.

When you use the override feature, take the following notes into consideration:

You can't override any properties of the attached disk other than the name of the disk while creating a VM from the machine image.
You must specify the replicaZones parameter for each attached regional persistent disk along with the regional disk's deviceName from the machine image.
If the source VM used to generate the machine image and the new VM belong to the same project and the same region, the following applies:
- Most of the properties of source instance and the new VM are the same. Properties that differ are those such as the ephemeral IP addresses that are auto assigned.
- If the source VM instance still exist when you create a new VM, then the new VM cannot use the same name and the same zone as the source instance.
If the source VM used to generate the machine image and the new VM belong to the same project but different regions, the following applies:
- You must override all zonal and regional resources for the new VM. For example, if you create a VM instance from a machine image whose source instance belonged to a different region, you need to override regional resources such as the subnetwork and regional firewall rules. However, global resources such as load balancers and service accounts don't need an override, unless you want to modify these.

Console

In the Google Cloud console, go to the Create an instance page.

Go to Create an instance
Click New VM instance from machine image.
Select your machine image and click Continue.
Optional: Customize the VM details.
Click Create.

For more setup details, see Create a VM instance from an image.

gcloud

Use the gcloud compute instances create command to create an instance from a machine image and add the properties you want to override.

For example, you can use the following gcloud command to create a VM called my-instance in the us-east1-b zone, from a machine image called my-machine-image. In this example overrides are applied to change the machine type, stop the host maintenance policy, and configure a regional persistent disk with the name regional-disk-0.

gcloud compute instances create my-instance \
    --zone=us-east1-b \
    --source-machine-image=my-machine-image \
    --machine-type=e2-standard-2 \
    --maintenance-policy=TERMINATE \
    --create-disk=device-name=boot-device-0,boot=true,auto-delete=true \
    --create-disk=device-name=regional-disk-0,\
      replica-zones=^:^us-east1-b:us-east1-c,boot=false

REST

To override machine image properties during VM creation, use the instances.insert() API and provide any fields you want to override in the request body.

In the API, construct a POST request to the instances.insert method. In the request body, include the sourceMachineImage parameter and any overrides that you need. You can add any property that you would normally set during instance creation. For example, to change the machine type, your API call would include the machineType parameter.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "machineType": "zones/ZONE/machineTypes/NEW_MACHINE_TYPE",
  "sourceMachineImage": "SOURCE_MACHINE_IMAGE_URL"
}

Replace the following:

PROJECT_ID: the project ID.
ZONE: the zone for the VM.
VM_NAME: the name of the VM to create.
NEW_MACHINE_TYPE: the machine type that you want to use for the VM.
SOURCE_MACHINE_IMAGE_URL: the full or partial URL of the machine image that you want to use to create the instance. For example, if you have a machine image called my-machine-image in a project called myProject. The following URLs are valid:
- https://www.googleapis.com/compute/v1/projects/myProject/global/machineImages/my-machine-image
- projects/myProject/global/machineImages/my-machine-image
- global/machineImages/my-machine-image

Override behavior

The override behavior in the API follows the JSON merge patch rules, described by RFC 7396. In summary, the following rules apply:

If you override a basic field, the corresponding basic field in the machine image is replaced with the basic field value in the request. Basic fields include parameters such as machineType and name.
If you override a repeated field, all repeated values for that property are replaced with the corresponding values provided in the request. Repeated fields are generally properties of type list. For example, disks and networkInterfaces are repeated fields.
If you override a nested object, the object in the machine image is merged with the corresponding object specification in the request. Note that if a nested object is within a repeated field, the field is treated according to rules for repeated fields. Labels are an exception to this rule, and are treated as a repeated field even though labels are of type object.

For example, if you want to create a VM from a machine image, and create regional persistent disks with the VM, use an override for the disks so you can specify the replicaZones option. Because the disks field is a repeated field, you must specify the disk configuration for all attached disks and the boot disk, not just the regional disks.

POST /compute/projects/my-proj/zones/us-west1-a/instances
{
  "name": "vm-from-image",
  "sourceMachineImage": "global/machineImages/my-machine-image",
  "disks": [
    {
      "kind": "compute#attachedDisks",
      "boot": true,
      "autoDelete": true,
      "deviceName": "boot-device",
      "initializeParams": {
        "sourceImage": "projects/my-proj/global/images/my-image",
        "diskType": "projects/my-proj/zones/us-west1-a/diskTypes/pd-standard",
      }
    },
    {
      "kind": "compute#attachedDisk",
      "boot": false,
      "autoDelete": true,
      "deviceName": "regional-device-0",
      "initializeParams": {
         "diskType": "projects/my-proj/zones/us-west1-a/diskTypes/pd-standard",
         "replicaZones": [
            "projects/my-proj/zones/us-west1-a",
            "projects/my-proj/zones/us-west1-c"
         ]
      }
    }
  ]
}

Create a VM using a machine image from a different project

Permissions required for this task

To perform this task, you must have the following permissions:

compute.instances.create on the project
compute.machineImages.useReadOnly on the machine image you want to use
Any additional permissions needed to set attributes on the instance, for example, the setTags permission

When you create a VM by using a machine image from a different project, you might not have access to the service account attached to that source project. If you want to create a VM from a machine image that is located in a different project, you need to ensure that you have access to the machine image and override the service account property on the new VM.

If you share a machine image across projects that use a Shared VPC network, you must explicitly specify the Shared VPC details when you create a VM from the machine image. For example, when you create a VM in a non-host project, provide the Shared VPC details of the host project using the --network, --subnet, or --network-interface options.

The following sections outlines how to create a VM from a a machine image located in a different project by using the Google Cloud CLI.

Grant access to the machine images that is stored in a different project.

Permissions can be granted on either the source project or the machine image. Use the gcloud compute machine-images add-iam-policy-binding command to grant the permissions on the machine image.
```
gcloud compute machine-images add-iam-policy-binding MACHINE_IMAGE_NAME \
    --project=MACHINE_IMAGE_PROJECT \
    --member='ACCOUNT_EMAIL' \
    --role='roles/compute.admin'
```
Replace the following:
- MACHINE_IMAGE_PROJECT: the project ID for the project that contains the source machine image.
- MACHINE_IMAGE_NAME: the name of the machine image that you want to add the permission binding to.
- ACCOUNT_EMAIL: the email address of the serviceAccount or user that is creating the VM. Ensure that the email is formatted to include the required prefix, the prefix must be one of the following:
  - user: specify this if the email address is associated with a user account. For example, user:user@example.com.
  - serviceAccount: specify this if the email address is associated with a service account. For example, serviceAccount:123456789000-compute@developer.gserviceaccount.com.
Example

For example, to add a compute.admin binding to the machine image called my-machine-image to the service account email 123456789000-compute@developer.gserviceaccount.com, use the following gcloud command:
```
gcloud compute machine-images add-iam-policy-binding my-machine-image \
    --project=machine-image-project \
    --member='serviceAccount:123456789000-compute@developer.gserviceaccount.com' \
    --role='roles/compute.admin'
```
Grant the user who runs the gcloud compute instances create command the Service Account User role (roles/iam.serviceAccountUser) on the service account associated with the machine image.
Use the gcloud compute instances create command to create a VM from a machine image.
```
gcloud compute instances create VM_NAME \
    --project=VM_PROJECT_ID \
    --zone=ZONE \
    --source-machine-image=projects/MACHINE_IMAGE_PROJECT/global/machineImages/MACHINE_IMAGE_NAME \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --subnet=SUBNET
```
Replace the following:
- VM_PROJECT_ID: the project ID for the project that you want to create the VM in
- VM_NAME: the name of the VM to create
- ZONE: the zone for the VM
- MACHINE_IMAGE_PROJECT: the project ID of the project where the machine image is located
- MACHINE_IMAGE_NAME: the machine image to create the VM from
- SERVICE_ACCOUNT_EMAIL: the email address of the service account that you want to attach to your VM
- SUBNET: if the subnet and instance are in the same project, replace SUBNET with the name of a subnet that is in the same region as the instance
  
  To specify a subnet in a Shared VPC network, replace SUBNET with a string in the following format:
```
projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
```
  Replace the following:
  - HOST_PROJECT_ID: the project ID of the Shared VPC host project
  - REGION: the region of the subnet
  - SUBNET_NAME: the name of the subnet
  Example
  
  For example, the following command creates a VM called my-instance in vm-project, in the us-east1-b zone, from a machine image called my-machine-image.
  
  The --service-account flag specifies the service account that you want to attach to the newly created VM. If you don't provide this flag, the source service account cannot be shared across both projects and the operation fails.
```
gcloud compute instances create my-instance \
 --project=vm-project \
 --zone=us-east1-b \
 --source-machine-image=projects/machine-image-project/global/machineImages/my-machine-image \
 --service-account=000123456789-compute@developer.gserviceaccount.com
```
  After the VM is created, the output resembles the following:
```
Created [https://www.googleapis.com/compute/v1/projects/project-12345/zones/us-east1-b/instances/my-instance].
NAME               ZONE        MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP   STATUS
my-instance        us-east1-b  e2-standard-2               192.0.2.1   203.224.0.113  RUNNING
```

What's next?

Learn more about machine images
Learn more about creating VM instances