Create machine images

Use a machine image to store all theconfiguration, metadata, permissions, and data from multiple disks for a VMinstance running on Compute Engine. The VM instance that you use to create amachine image is referred to as asource VM instance.

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

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

Before you begin

Limitations and restrictions

  • You can create a machine image of a specific instance at most 6 times every60 minutes.
  • You can protect a machine image by using eitherCloud Key Management Service (Cloud KMS) or acustomer-supplied encryption key (CSEK).The encryption key protects the content of the disks. However, metadata isn'tprotected.
  • If you use a CSEK to protect your machine image, a full copy of all disk datais stored during the generation of the machine image. In all other scenariosdisk data is stored indifferential copies.

  • You can't create machine images from source VMs that:

    • Have greater than 200 TB of disks attached.
    • Don't have any attached disks.
    • Have any attached Hyperdisk volumes.
    • Use Z3 machine type except forz3-highmem-192-highlssd-metal.
    • Use a C3D, H3, or A3 machine type.

    For instances that don't support the creation of machine images, you caninstead create an OS image from the boot disk of the instance, as described inCreate custom images.

Instance and disk properties not supported by machine image

When you create machine images from VM instances or create VM instances frommachine images, the following instance and disk properties are not preservedor restored:

  • disks.architecture
  • disks.description
  • disks.labels
  • disks.locked
  • disks.multiWriter
  • disks.onUpdateAction
  • disks.provisionedIops
  • disks.shieldedInstanceInitialState
  • disks.sourceImage
  • disks.sourceImageEncryptionKey
  • disks.sourceInstantSnapshot
  • disks.sourceSnapshot
  • disks.sourceSnapshotEncryptionKey
  • privateIpv6GoogleAccess
  • resourceManagerTags
  • resourcePolicies
  • secure_tag
  • shieldedInstanceConfig

Creating a machine image from a VM

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • 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 theGoogle Cloud console, theGoogle Cloud CLI, orREST.

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 VM instance.
  • The zone that the source VM instance is located in.
  • An optional description.
  • An optionalstorageLocation.If you don't specify a location, the default storage location is themultiregional Cloud Storage locationof the source VM instance.
  • An optional encryption key. You can choose between a Google-owned and Google-managed encryption key, aCloud Key Management Service (Cloud KMS) key or acustomer-supplied encryption (CSEK)key. If no encryption key is specified, machine images are encrypted usinga Google-owned and Google-managed encryption key.

  • If you want to use a machine image forinstance cloning and snapshotting,remove the OS and app information that is unique to the instance beforegenerating the machine image from an instance. For example, for Windows VMinstances, useGCESysprep to prepare the system for replication.

Console

  1. In the Google Cloud console, go to theMachine images page.

    Go to Machine images

  2. ClickCreate Machine image.

  3. Specify aName for your machine image.

  4. Optional: Provide aDescription.

  5. Select theSource VM instance.

  6. Optional: Specify where to store the machine image. Choose betweenMulti-regionalorRegional storage. For more information about location, seeMachine image storage location.

  7. Optional: Select anEncryption method.

  8. ClickCreate.

gcloud

Use thegcloud compute machine-images createcommand to create a machine image from an instance.

gcloud compute machine-images createMACHINE_IMAGE_NAME \    --source-instance=SOURCE_VM_NAME

Replace the following:

  • MACHINE_IMAGE_NAME: name of the machineimage that you want to create.
  • SOURCE_VM_NAME: name of the sourceVM instance that you want to create the image from.

Example

For example, you can use the followinggcloud command to create a machineimage calledmy-machine-image from a source instance calledmy-instance:

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

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

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

REST

In the API, construct aPOST request to themachineimages.insertmethod. In the request body, include the followingPOST request:

POST https://compute.googleapis.com/compute/v1/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 machineimage that you want to create.

  • SOURCE_INSTANCE_URL: full or partial URL ofthe source VM instance that you want to use to create the machine image.For example, if you have a source instance calledmy-instance ina project calledmyProject. 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?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.