After you create a machine image, you can use it to make copies of the sourcecompute instance. For more information about the uses of machine images, seewhen to use a machine image.

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

A machine image is unchangeable. However, you canoverride almost all the properties ofthe machine image when creating an instance from the machine image.

You can create instances from machine images using either theGoogle Cloud console, theGoogle Cloud CLI, orREST.

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud 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.

  Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate 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 theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the compute instance or project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined 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 anerror 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 createshort-lived machine images from the new instances. You can then create therequired number of instances from the new machine images.

• If you use the gcloud CLI or REST to create an instancefrom a machine image with CMEK-encrypted disks, the disks on the newinstance are encrypted using default encryption unless you specify the CMEKkeys. If you use the Google Cloud console, CMEK encryption isinherited automatically.

• You cannot create instances from machine images with attached regionaldisks using the Google Cloud console. Use the Google Cloud CLI or RESTand specify thereplicaZones anddeviceName parameters for each attachedregional disk. For more information,seeCreate 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 withno changes to the properties, use this method.

gcloud compute instances createINSTANCE_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   STATUSmy-instance        us-east1-b  e2-standard-2               192.0.2.1   203.224.0.113  RUNNING

gcloud compute instances createINSTANCE_NAME \    --zone=ZONE \    --source-machine-image=SOURCE_MACHINE_IMAGE \    --create-disk=auto-delete=yes,boot=yes,device-name=DEVICE_NAME_IN_IMAGE,kms-key=KMS_KEY,kms-project=KMS_PROJECT,kms-location=KMS_LOCATION,kms-keyring=KMS_KEYRING \    --create-disk=auto-delete=yes,boot=no,device-name=DEVICE_NAME_IN_IMAGE,kms-key=KMS_KEY,kms-project=KMS_PROJECT,kms-location=KMS_LOCATION,kms-keyring=KMS_KEYRING

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "INSTANCE_NAME",  "sourceMachineImage": "SOURCE_MACHINE_IMAGE_URL"}

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "INSTANCE_NAME",  "sourceMachineImage": "SOURCE_MACHINE_IMAGE_URL",  "disks": [    {      "boot": true,      "autoDelete": true,      "deviceName": "DEVICE_NAME_IN_IMAGE",      "diskEncryptionKey": {        "kmsKeyName": "projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING/cryptoKeys/KMS_KEY"      }    },    {      "boot": false,      "autoDelete": true,      "deviceName": "DEVICE_NAME_IN_IMAGE",      "diskEncryptionKey": {        "kmsKeyName": "projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING/cryptoKeys/KMS_KEY"      }    }  ]}

Create an instance from a machine image with property overrides

If you want to create an instance primarily based on the machine image butwith a few changes, you can use the override behavior. To use the overridebehavior, you pass in attributes to override existing machine image propertieswhen 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 nameof the disk while creating an instance from the machine image.

• You must specify thereplicaZones parameter for each attached regionaldisk along with the regional disk'sdeviceName from the machineimage.

• If the source instance (used to generate the machine image) and thenew instance belong to the same project and the same region, the followingapplies:

  • 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 areauto assigned.
  • If the source instance still exists when you create a new instance, thenthe new instance cannot use the same name and the same zone as the sourceinstance.

• If the source instance used to generate the machine image and the new instancebelong 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 sourceinstance belonged to a different region, you need to override regionalresources such as the subnetwork and regional firewall rules. However,global resources such as load balancers and service accounts don't need anoverride, 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 patchrules, described byRFC 7396.In summary, the following rules apply:

• If you override a basic field, the corresponding basic fieldin the machine image is replaced with the basic field valuein the request. Basic fields include parameters such asmachineType andname.
• If you override a repeated field, all repeated values for that propertyare replaced with the corresponding values provided in the request.Repeated fields are generally properties of typelist. For example,disks andnetworkInterfaces are repeated fields.
• If you override anested object, the object in the machine imageis merged with the corresponding object specification inthe request. Note that if a nested object is within a repeated field,the field is treated according to rules for repeated fields. Labels arean exception to this rule, and are treated as a repeated field eventhough labels are of typeobject.

For example, if you want to create a VM from a machine image, and createregional disks with the VM, use an override for the disks so youcan specify thereplicaZones option. Because thedisksfield is a repeated field, you must specify the disk configuration for allattached 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 thatsource project. If you want to create an instance from a machine image that islocated in a different project, you need to ensure that you have access to themachine image and override the service account property on the new instance.

If you share a machine image across projects that use a Shared VPCnetwork, you must explicitly specify the Shared VPC details when youcreate an instance from the machine image. For example, when you create aninstance in a non-host project, provide the Shared VPC details of thehost project using the--network,--subnet, or--network-interfaceflags.

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

1. Grant accessto the machine image that is stored in a different project.

   Permissions can be granted on either the source project or the machineimage. Use thegcloud compute machine-images add-iam-policy-binding commandto grant the permissions on the machine image.

   gcloud compute machine-images add-iam-policy-bindingMACHINE_IMAGE_NAME \    --project=MACHINE_IMAGE_PROJECT \    --member='ACCOUNT_EMAIL' \    --role='roles/compute.admin'

   Replace the following:

   • MACHINE_IMAGE_PROJECT: the project ID for theproject that contains the source machine image.
   • MACHINE_IMAGE_NAME: the name of the machine imagethat you want to add the permission binding to.

   • ACCOUNT_EMAIL: the email address of theserviceAccount oruser that is creating the instance. Ensure that theemail is formatted to include the required prefix. The prefix must beone of the following:

     • user: specify this if the email address is associated with a useraccount. For example,user:user@example.com.
     • serviceAccount: specify this if the email address is associated witha service account. For example,serviceAccount:123456789000-compute@developer.gserviceaccount.com.

   Example

   For example, to add acompute.admin binding to the machine image calledmy-machine-image tothe service account email123456789000-compute@developer.gserviceaccount.com,use the followinggcloud 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 thegcloud compute instances create command theService Account User role(roles/iam.serviceAccountUser) on the service account associated with themachine image.

3. Use thegcloud compute instances create commandto create an instance from a machine image.

   gcloud compute instances createINSTANCE_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 theproject that you want to create the instance in
   • INSTANCE_NAME: a name for the instance
   • ZONE: thezone for the instance
   • MACHINE_IMAGE_PROJECT: the project ID of theproject where the machine image is located
   • MACHINE_IMAGE_NAME: the machine image to createthe instance from
   • SERVICE_ACCOUNT_EMAIL: the email address of theservice account that you want to attach to your instance

   • SUBNET: if the subnet and instance are in thesame project, replaceSUBNET with the name of a subnet thatis in the same region as the instance

     To specify a subnet in a Shared VPC network, replaceSUBNET 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 calledmy-instance invm-project, in theus-east1-b zone, from a machine image calledmy-machine-image.

     The--service-account flag specifies the service account that you wantto attach to the newly created VM. If you don't providethis flag, the source service account cannot be shared across both projectsand 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   STATUSmy-instance        us-east1-b  e2-standard-2               192.0.2.1   203.224.0.113  RUNNING

What's next?

• Learn more aboutmachine images
• Learn more aboutcreating Compute Engine instances