Creating machine images

Beta

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Use a machine image to store all the configuration, metadata, permissions, and data from one or more disks for a VM instance running on Compute Engine. The VM instance that you use to create a machine image is referred to as a source instance.

For information about when and how to use machine images, see Machine images.

This document describes the steps for creating a machine image from a source instance.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.

Limitations and restrictions

• You can share a machine image across projects. However, shared VPC networks aren't supported.
• You can protect a machine image by using either Cloud Key Management Service (Cloud KMS) or a customer-supplied encryption key (CSEK). The encryption key protects the content of the disks. However, metadata isn't protected.
• If you use a CSEK to protect your machine image, a full copy of all disk data is stored during the generation of the machine image. In all other scenarios disk data is stored in differential copies.

Creating a machine image from an instance

Permissions required for this task

To perform this task, you must have the following permissions:

• compute.machineImages.create on the project
• compute.instances.useReadOnly on the source instance
• compute.disks.createSnapshot on the disk

You can create machine images using either the Google Cloud Console, the gcloud command-line tool, or the Compute Engine API.

To create a machine image, you need the following information:

• A name for the machine image that you want to create.
• The name of the source instance.
• The zone that the source instance is located in.
• An optional description.
• An optional storageLocation. If you do not specify a location, the default storage location is the multiregional Cloud Storage location of the source instance.
• An optional encryption key. You can choose between a Google-managed key, a Cloud Key Management Service (Cloud KMS) key or a customer-supplied encryption (CSEK) key. If no encryption key is specified, machine images are encrypted using a Google-managed key.

• If you want to use a machine image for instance cloning and replication, remove the OS and app information that is unique to the instance before generating the machine image from an instance. For example, for Windows VM instances, use GCESysprep to prepare the system for replication.

console

1. In the Google Cloud Console, go to the Machine images page.

   Go to Machine images

2. Click Create Machine image.

3. Specify a Name for your machine image.

4. Optional: Provide a Description.

5. Select the Source VM instance.

6. Optional: Specify where to store the machine image. Choose between Multi-regional or Regional storage. For more information about location, see Machine image storage location.

7. Optional: Select an Encryption method.

8. Click Create.

gcloud

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

gcloud beta compute machine-images create MACHINE_IMAGE_NAME \
    --source-instance SOURCE_INSTANCE_NAME

Replace the following:

• MACHINE_IMAGE_NAME: name of the machine image that you want to create.
• SOURCE_INSTANCE_NAME: name of the source instance that you want to create the image from.

Example

For example, you can use the following gcloud command to create a machine image called my-machine-image from a source instance called my-instance:

gcloud beta compute machine-images create my-machine-image  \
    --source-instance my-instance

The process takes a few minutes. When the machine image is created, you get an output that resembles the following:

Created [https://www.googleapis.com/compute/beta/projects/project-12345/global/machineImages/my-machine-image].
NAME               STATUS
my-machine-image   READY

API

In the API, construct a POST request to the machineimages.insert method. In the request body, include the following POST request:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/machineImages

{
  "name": "MACHINE_IMAGE_NAME",
  "sourceInstance": "SOURCE_INSTANCE_URL"
}

Replace the following:

• PROJECT_ID: project ID.
• MACHINE_IMAGE_NAME: name of the machine image that you want to create.

• SOURCE_INSTANCE_URL: full or partial URL of the source instance that you want to use to create the machine image. For example, if you have a source instance called my-instance in a project called myProject. The following URLs are valid:

  • https://www.googleapis.com/compute/v1/projects/myProject/global/instances/my-instance
  • projects/myProject/global/instances/my-instance
  • global/instances/my-instance

What's next?

• Learn more about machine images
• Create VM instances from machine images