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, 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 as follows.
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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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.
-
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
anddeviceName
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)
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.
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 calledmy-machine-image
in a project calledmyProject
. 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
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'sdeviceName
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.
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 calledmy-machine-image
in a project calledmyProject
. 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
andname
. - 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
andnetworkInterfaces
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 typeobject
.
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
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 theserviceAccount
oruser
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:[email protected]
.serviceAccount:
specify this if the email address is associated with a service account. For example,serviceAccount:[email protected]
.
Example
For example, to add a
compute.admin
binding to the machine image calledmy-machine-image
to the service account email[email protected]
, use the followinggcloud
command:gcloud compute machine-images add-iam-policy-binding my-machine-image \ --project=machine-image-project \ --member='serviceAccount:[email protected]' \ --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 inVM_NAME
: the name of the VM to createZONE
: the zone for the VMMACHINE_IMAGE_PROJECT
: the project ID of the project where the machine image is locatedMACHINE_IMAGE_NAME
: the machine image to create the VM fromSERVICE_ACCOUNT_EMAIL
: the email address of the service account that you want to attach to your VMSUBNET
: 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 instanceTo 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 projectREGION
: the region of the subnetSUBNET_NAME
: the name of the subnet
Example
For example, the following command creates a VM called
my-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 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