Creating instances from machine images

After you create a machine image, you can then use this machine image to create a new 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 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.

console

  1. Go to the VM instances page.

    Go to the VM instances page

  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 for your new instance.
  • ZONE: The zone that you want to use for your new instance.
  • SOURCE_MACHINE_IMAGE_NAME: The machine image that you want to use to create the instance.

Example

For example, you can use the following gcloud command to create an instance 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

When the new instance is created, you get an output that 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 is the zone that you want to use for your new instance.
  • VM_NAME: The name of the instance that you want to create.
  • 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

Creating an instance using a machine image from a different 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. The following sections outlines how to create an instance from a a machine image located in a different project 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='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.
    • 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.
      • 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 an instance from a machine image.

    gcloud beta compute instances create VM_NAME \
        --project=VM_PROJECT \
        --zone ZONE \
        --source-machine-image projects/PROJECT_ID/global/machineImages/MACHINE_IMAGE_NAME \
        --service-account service-account-email
    

    Replace the following:

    • VM_PROJECT: The project ID for the project that you want to create the new VM.
    • VM_NAME: The name for your new VM.
    • ZONE: The zone that you want to use for your new VM.
    • PROJECT_ID: The project ID of the project where the machine image is located.
    • MACHINE_IMAGE_NAME: The machine image that you want to use to create the VM.
    • SERVICE_ACCOUNT: The service account email associated with the VM project.

      Example

      For example, to create an instance 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 tag specifies the service account for the VM project. If you do not provide this tag, 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
      

      When the new instance is created, you get an output that 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 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.

You can override most of the instance 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 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 VM instance still exist 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 VM used to generate the machine image and the new VM 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 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. Go to the VM instances page.

    Go to the VM instances page

  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. Read create an instance for additional setup details.

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 an instance 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 instance 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: Your project ID.
  • ZONE: The zone that you want to use for your new instance.
  • VM_NAME: The name of the instance that you want to create.
  • NEW_MACHINE_TYPE: The machine type that you want to use for the new instance.
  • 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?