Create Compute Engine instances from machine images

After you create a machine image, you can use it to make copies of the source compute 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

  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.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create Compute Engine instances from machine images, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the compute instance or project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Restrictions

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

• You can create at most 6 instances 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 instances than the defined limit (6 instances in 60 minutes), create additional machine images from the source instance, or create short-lived machine images from the new instances. You can then create the required number of instances from the new machine images.

• You cannot create instances from machine images with attached regional disks using the Google Cloud console. Use the Google Cloud CLI or REST and specify the replicaZones and deviceName parameters for each attached regional disk. For more information, see Create an instance from a machine image with property overrides.

Create an instance from a machine image (no override)

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

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

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

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

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

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

Create an instance from a machine image with property overrides

If you want to create an instance 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 an instance from the machine image.

• You must specify the replicaZones parameter for each attached regional disk along with the regional disk's deviceName from the machine image.

• If the source instance (used to generate the machine image) and the new instance belong to the same project and the same region, the following applies:

  • Most of the properties of source instance and the new instance are the same. Properties that differ are those such as the ephemeral IP addresses that are auto assigned.
  • If the source instance still exists when you create a new instance, then the new instance cannot use the same name and the same zone as the source instance.

• If the source instance used to generate the machine image and the new instance belong to the same project but different regions, the following applies:

  • You must override all zonal and regional resources for the new instance. For example, if you create an 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.

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

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

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

Override behavior

The override behavior in the Compute Engine 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 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 https://compute.googleapis.com/compute/v1/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 an instance using a machine image from a different project

When you create an instance 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 an instance 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 instance.

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 an instance from the machine image. For example, when you create an instance in a non-host project, provide the Shared VPC details of the host project using the --network, --subnet, or --network-interface flags.

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

1. Grant access to the machine image 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 instance. 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 CLI 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'
   

2. 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.

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

   gcloud compute instances create INSTANCE_NAME \
       --project=INSTANCE_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:

   • INSTANCE_PROJECT_ID: the project ID for the project that you want to create the instance in
   • INSTANCE_NAME: a name for the instance
   • ZONE: the zone for the instance
   • MACHINE_IMAGE_PROJECT: the project ID of the project where the machine image is located
   • MACHINE_IMAGE_NAME: the machine image to create the instance from
   • SERVICE_ACCOUNT_EMAIL: the email address of the service account that you want to attach to your instance

   • 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 Compute Engine instances