Use a machine image to store all the configuration, metadata, permissions, and data from multiple 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 VM 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 VM instance.
Before you begin
- If you want to use the command-line examples in this guide, do the following:
- Install or update to the latest version of the Google Cloud CLI.
- 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 create a machine image at most once every 10 minutes. If you want to issue a burst of requests for creating multiple machine images from an instance, you can issue at most 6 requests in 60 minutes.
- 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.
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 regional persistent disks.
- Have any attached Hyperdisk Extreme disks.
Instance and disk properties not supported by machine image
When you create machine images from VM instances or create VM instances from machine images, the following instance and disk properties are not preserved or 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
You can create machine images using either the Google Cloud console, the Google Cloud CLI, 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 VM instance.
- The zone that the source VM 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 VM 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 snapshotting, 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
In the Google Cloud console, go to the Machine images page.
Click Create Machine image.
Specify a Name for your machine image.
Optional: Provide a Description.
Select the Source VM instance.
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.
Optional: Select an Encryption method.
Click Create.
gcloud
Use the
gcloud compute machine-images create
command to create a machine image from an instance.
gcloud compute machine-images create MACHINE_IMAGE_NAME \ --source-instance=SOURCE_VM_NAME
Replace the following:
MACHINE_IMAGE_NAME
: name of the machine image that you want to create.SOURCE_VM_NAME
: name of the source VM 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 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/v1/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/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 machine image that you want to create.SOURCE_INSTANCE_URL
: full or partial URL of the source VM instance that you want to use to create the machine image. For example, if you have a source instance calledmy-instance
in a 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?
- Learn more about machine images
- Create VM instances from machine images