Creating, Deleting, and Deprecating Custom Images

You can create custom images of boot disks and use these images to create new instances. This is ideal for situations where you have created and modified a persistent boot disk to a certain state and need to save that state to create new instances.

Alternatively, you can use the virtual disk import tool to import boot disk images to Compute Engine from your existing systems and add them to your custom images list.

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.
Read the Images page.

Creating a custom image

These instructions describe how to create a custom image on a Linux instance. For instructions on creating a Windows image, see Creating a Windows image.

Optionally, you can also use Identity and Access Management (IAM) to share the image with other projects.

Preparing your instance for an image

You can create an image from a disk even while it is attached to a running VM instance. However, your image will be more reliable if you put the instance in a state that is easier for the image to capture. Use one of the following processes to prepare your boot disk for the image:

Stop the instance so that it can shut down and stop writing any data to the persistent disk.
If you cannot stop your instance before you create the image, minimize the amount of writes to the disk and sync your file system.
1. Pause applications or operating system processes that write data to that persistent disk.
2. Run an application flush to disk if necessary. For example, MySQL has a FLUSH statement. Other applications might have similar processes.
3. Stop your applications from writing to your persistent disk.
4. Run sudo sync.

After you prepare the instance, create the image.

Creating the image

You can create disk images from the following sources:

A persistent disk, even while that disk is attached to an instance.
A snapshot of a persistent disk
Another image in your project
An image that is shared from another project
A compressed RAW image in Google Cloud Storage

You cannot use the console to create images from snapshots. Use the gcloud command-line tool or the API to create images from snapshots.

Console

In the Google Cloud Platform Console, go to the Create an image page.
Go to the Create an image page
Specify the source from which you want to create an image. This can be a persistent disk, another image, or a disk.raw file in Google Cloud Storage.
Specify the properties for your image. For example, you can specify an image family name for your image to organize this image as part of an image family.
If you are creating an image from a disk attached to a running image, check "Force creation from running instance" to confirm that you want to create the image while the instance is running.
Click Create to create the image.

gcloud

Create an image from a persistent disk:

gcloud compute images create [IMAGE_NAME] \
  --source-disk [SOURCE_DISK] \
  --source-disk-zone [ZONE] \
  --family [IMAGE_FAMILY] \
  [--force]

where:

[IMAGE_NAME] is a name for the new image.
[SOURCE_DISK] is the disk from which you want to create the new image.
[ZONE] is the zone where the disk is located.
[IMAGE_FAMILY] is an optional flag that specifies which image family this image belongs to.
[--force] is an optional flag that allows you to create the image from a running instance. By default, you cannot create images from running instances. Specify this flag only if you are sure that you want to create the image while the instance is running.

Create an image from another image:

gcloud compute images create [IMAGE_NAME] \
  --source-image [SOURCE_IMAGE] \
  --source-image-project [IMAGE_PROJECT] \
  --family [IMAGE_FAMILY]

where:

[IMAGE_NAME] is a name for the new image.
[SOURCE_IMAGE] is the image from which you want to create the new image.
[IMAGE_PROJECT] is an optional parameter that specifies which project the source image is located in. Use this parameter if you want to copy an image from another project.
[IMAGE_FAMILY] is an optional flag that specifies which image family this new image belongs to.

Create an image from a snapshot:

gcloud compute images create [IMAGE_NAME] \
  --source-snapshot [SOURCE_SNAPSHOT]

where:

[IMAGE_NAME] is a name for the new image.
[SOURCE_SNAPSHOT] is the snapshot from which you want to create the new image.

API

Make a POST request to the images().insert method, a URL in the request body that points to the source object from which you want to create the image. Specify URLs to your resources using your own project ID and resource names.

Create an image from a persistent disk:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images

{
  "name": "[IMAGE_NAME]",
  "sourceDisk": "/zones/[ZONE]/disks/[SOURCE_DISK]",
  "forceCreate": "[FORCE_CREATE]"
}

where:

[SOURCE_DISK] is the disk from which you want to create the image.
[ZONE] is the zone where the source disk is located.
[PROJECT_ID] is the project to which the image belongs.
[IMAGE_NAME] is a name for the new image that you want to create.
[ZONE] is the zone where the disk belongs.
[FORCE_CREATE] is an optional parameter that allows you to create the image from a running instance. Specify TRUE only if you are sure that you want to create the image from a running instance. The default value if you do not specify this parameter is FALSE.

Create an image from another image:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images

{
  "name": "[IMAGE_NAME]",
  "sourceImage": "/global/images/[SOURCE_IMAGE]"
}

where:

[PROJECT_ID] is the project to which the image belongs.
[IMAGE_NAME] is a name for the new image that you want to create.
[SOURCE_IMAGE] is the image from which you want to create the image.

Create an image from a snapshot:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images

{
  "name": "[IMAGE_NAME]",
  "sourceSnapshot": "/[SOURCE_PROJECT_ID]/global/snapshots/[SOURCE_SNAPSHOT]"
}

where:

[PROJECT_ID] is the project to which the image belongs.
[IMAGE_NAME] is a name for the new image that you want to create.
[SOURCE_SNAPSHOT] is the snapshot from which you want to create the image.
[SOURCE_PROJECT_ID] is an optional variable that specifies which project the snapshot is located in. You must have permission to access the snapshot resource in that project.

For more information about adding images, see the images reference.

Deprecating an image

Google Compute Engine lets you deprecate a custom image that you own by setting the deprecation status on the image. Each deprecation status causes a different response from the server, helping you transition users away from unsupported images in a manageable way.

To set the deprecation status of an image, run the following command:

gcloud compute images deprecate [IMAGE] --state [STATE] --replacement [REPLACEMENT]

where, [IMAGE] is the name of the image to deprecate.

The deprecation state can be any of:

DEPRECATED - This image is considered deprecated. When users attempt to use this image, the request will succeed but Google Compute Engine also returns a warning. New links to this image are still allowed. Image families no longer point to this image even if it is the most recent image in a family.
OBSOLETE - This image is obsolete and new users cannot use it. Google Compute Engine returns an error if users try to use the image in their requests. Existing links to this image are still allowed.
DELETED - This image is deleted and users cannot use it. Google Compute Engine returns an error if users attempt to use the image.

Deleting an image

You can only delete custom images that you or someone who has access to the project has added. To delete an image, run the following command:

gcloud compute images delete [IMAGE]

where [IMAGE] is the name of the image to delete.

Setting image versions in an image family

Use image families to simplify image versioning. Add an image to an image family to set it as the most recent image version. If you determine that you must roll back the image family to a previous image version, deprecate the most recent image in the family.

For example, create an image named image-v1 as part of an image family.

gcloud compute images create image-v1 \
          --source-disk disk-1 \
          --source-disk-zone us-central1-f \
          --family my-image-family

The image family points to image-v1. Add a second image to the family:

gcloud compute images create image-v2 \
          --source-disk disk-2 \
          --source-disk-zone us-central1-f \
          --family my-image-family

The image family points to image-v2 because it is the most recent image that you added to the image family. You can see which image a family points to by running the gcloud compute images describe-from-family command. For example:

gcloud compute images describe-from-family my-image-family

family: my-image-family
id: '8904691942610171306'
kind: compute#image
name: image-v2
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/images/image-v2
sourceDisk: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v2
sourceDiskId: '1677449456001963379'
sourceType: RAW
status: READY

If you determine that you must roll back the image family so that it no longer points to image-v2, deprecate image-v2 and the family will once again point to image-v1.

gcloud compute images deprecate image-v2 --state DEPRECATED --replacement image-v1

Check to make sure that the image family points to image-v1 again:

gcloud compute images describe-from-family my-image-family

family: my-image-family
id: '2741732787056801255'
kind: compute#image
name: image-v1
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/images/image-v1
sourceDisk: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v1
sourceDiskId: '1677449456001963379'
sourceType: RAW
status: READY

Enabling guest operating system features on custom images

You can set the guestOsFeatures parameter when you create a custom image. This parameter enables one or more features for VM instances that use the image for their boot disks. The following features are available:

MULTI_IP_SUBNET - For configuring interfaces with a netmask other than /32.
SECURE_BOOT - Enables UEFI secure boot, which restricts unsigned software from booting or unsigned drivers from loading on the VM instance.
UEFI_COMPATIBLE - Enables UEFI booting, which is an alternative system boot method. Most public images use the GRUB bootloader as their primary boot method.
VIRTIO_SCSI_MULTIQUEUE - Enables multiqueue SCSI capabilities for Local SSD devices. This option is an alternative to NVMe.
- For Linux images, you can enable VIRTIO_SCSI_MULTIQUEUE on images with kernel versions 3.17 and higher.
- For Windows images, you can enable VIRTIO_SCSI_MULTIQUEUE on images with driver version 1.2.0.1621 or higher.
WINDOWS - Required for Windows Server images. Newer public images for Windows server include the WINDOWS parameter to indicate that it is a Windows image.

Use the gcloud command-line tool or the API to enable guest operating system features on your custom images.

gcloud

Create a custom image from one of your existing custom images, but also include the --guest-os-features flag.

gcloud compute images create [IMAGE_NAME] \
  --source-image [SOURCE_IMAGE] \
  --source-image-project [IMAGE_PROJECT] \
  --guest-os-features="[FEATURE_ID],..."

where:

[IMAGE_NAME] is a name for the new image that you want to create.
[SOURCE_IMAGE] is the image from which you want to create the new image.
[IMAGE_PROJECT] is an optional parameter that specifies which project the source image is located in. Use this parameter if you want to copy an image from another project.
[FEATURE_ID] is an ID for one of the available guest OS features. You can specify multiple features as a comma-separated list.

API

Make a POST request to the images().insert method, a URL in the request body that points to the source object from which you want to create the image. Replace the project and zone with your own project ID and the zone of the persistent disk:

Create an image from a persistent disk:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images

{
 "name": "[IMAGE_NAME]",
 "sourceImage": "projects/[IMAGE_PROJECT]/global/images/[SOURCE_IMAGE]",
 "guestOsFeatures": [
  {
   "type": "[FEATURE_ID]"
  }
 ]
}

where:

[IMAGE_NAME] is a name for the new image that you want to create.
[SOURCE_IMAGE] is the image from which you want to create the new image.
[IMAGE_PROJECT] is a parameter that specifies which project the source image is located in.
[FEATURE_ID] is an ID for one of the available guest OS features. You can specify multiple features as a comma-separated list.

For more information about adding images, see the images reference.

What's next

Share your private image with other projects.
Learn how to import an existing image.
Learn how to export an image to Google Cloud Storage.
Learn how to start an instance from an image.

Was this page helpful? Let us know how we did:

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

Last updated September 27, 2018.

Creating, Deleting, and Deprecating Custom Images

Before you begin

Creating a custom image

Preparing your instance for an image

Creating the image

Console

gcloud

API

Deprecating an image

Deleting an image

Setting image versions in an image family

Enabling guest operating system features on custom images

gcloud

API

What's next

Send feedback about...