Creating VM instances from machine images

After you create a machine image, you can then use this machine image to create a virtual machine (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 creating 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 gcloud command-line tool, or the Compute Engine API.

Before you begin

Creating 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

  1. In the Google Cloud Console, go to the VM instances page.

    Go to VM instances

  2. Click Create instance.

  3. Click New VM instance from machine image.

  4. Select your machine image and click Continue.

  5. Specify a name for your instance.

  6. Click Create.

gcloud

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

gcloud beta 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 beta 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/beta/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

API

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/beta/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

Creating a VM using a machine image from a different 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. The following sections outlines how to create a VM from a a machine image located in a different project by using the gcloud command-line tool.

  1. 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. To grant the permissions on the machine image using the gcloud command-line tool, run the following command:

    gcloud beta 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.

    gcloud beta 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. Use the gcloud beta compute instances create command to create a VM from a machine image.

    gcloud beta compute instances create VM_NAME \
        --project=VM_PROJECT_ID \
        --zone ZONE \
        --source-machine-image projects/MACHINE_PROJECT_ID/global/machineImages/MACHINE_IMAGE_NAME \
        --service-account SERVICE_ACCOUNT_EMAIL
    

    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_PROJECT_ID: 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 serviceAccount that is creating the VM.

      Example

      For example, to create a VM called my-instance in the us-east1-b zone, from a machine image called my-machine-image that is located in a project called vm-project.

      The service-account flag specifies the service account for the VM project that you want to create the machine image in. If you do not provide this flag, the source service account cannot be shared across both projects and the operation fails.

      gcloud beta compute instances create my-instance \
       --project=vm-project \
       --zone us-east1-b \
       --source-machine-image projects/project-67890/global/machineImages/my-machine-image \
       --service-account 123456789000-compute@developer.gserviceaccount.com
      

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

      Created [https://www.googleapis.com/compute/beta/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
      

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.

You can override most of the VM properties from the machine image. When you use the override feature, take the following notes into consideration:

  • 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

  1. In the Google Cloud Console, go to the VM instances page.

    Go to VM instances

  2. Click Create instance.

  3. Click New VM instance from machine image.

  4. Select your machine image and click Continue.

  5. Specify a name for your instance.

  6. Update the properties that you want to change.

  7. Click Create. For more setup details, see create an instance .

gcloud

Use the gcloud beta 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 and stop the maintenance policy.

gcloud beta compute instances create my-instance \
    --zone us-east1-b \
    --source-machine-image my-machine-image \
    --machine-type e2-standard-2 \
    --maintenance-policy TERMINATE

API

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/beta/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 primitive field, the corresponding primitive field in the machine image is replaced with the primitive field value in the request. Primitive 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.

What's next?