Creating, deleting, and deprecating custom images

Linux VMs Windows VMs

You can create custom images from source disks, images, snapshots, or images stored in Cloud Storage and use these images to create virtual machine (VM) instances. This is ideal for situations where you have created and modified a persistent boot disk or specific image to a certain state and need to save that state for creating 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 document.

Creating a custom image

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

You must use Identity and Access Management (IAM) permissions to share images with other projects.

Selecting an image storage location

When creating a custom image, you can specify the image's Cloud Storage location, excluding dual-region locations. By specifying the image storage location, you can meet your regulatory and compliance requirements for data locality as well as your high availability needs by ensuring redundancy across regions.

The storage location feature is optional. If you do not select a location, Compute Engine stores your image in the multi-region closest to the image source.

To see the location where an image is currently stored, use the images describe command from gcloud compute:

gcloud compute images describe IMAGE_NAME \
    --project=PROJECT_ID

All of your existing images prior to this feature launch remain where they are, the only change is that you can view the image location of all your images. If you have an existing image you want to move, you must recreate it in the desired location.

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 can't stop your instance before you create the image, minimize the amount of writes to the disk and sync your file system.
1. Pause apps or operating system processes that write data to that persistent disk.
2. Run an app flush to disk if necessary. For example, MySQL has a FLUSH statement. Other apps might have similar processes.
3. Stop your apps 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 Cloud Storage

You can create a disk image once every 10 minutes. If you want to issue a burst of requests to create a disk image, you can issue at most 6 requests in 60 minutes. For more information, see Snapshot frequency limits.

Console

In the Google Cloud Console, go to the Create an image page.

Go to Create an image
Specify the Name of your image.
Specify the Source from which you want to create an image. This can be a persistent disk, a snapshot, another image, or a disk.raw file in Cloud Storage.
Specify the Location at which to store your image. Choose your image storage location from the Based on source disk location (default) drop-down list. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you don't make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.
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.
Click Create to create the image.

gcloud

In the gcloud command-line tool, use the gcloud compute images create command to create a custom image.

Create an image from a source disk:

The --force flag is an optional flag that lets you 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.

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

Replace the following:

IMAGE_NAME: a name for the new image
SOURCE_DISK: the disk from which you want to create the image
ZONE: the zone where the disk is located
IMAGE_FAMILY: Optional: a flag that specifies which image family this image belongs to
LOCATION: Optional: a flag that lets you designate the region or multi-region where your image is stored. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you don't make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

Create an image from a source image:

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

Replace the following:

IMAGE_NAME: a name for the new image.
SOURCE_IMAGE: the image from which you want to create the new image.
IMAGE_PROJECT: Optional: the project the source image is located in. Use this parameter if you want to copy an image from another project.
IMAGE_FAMILY: Optional: the image family this new image belongs to.
LOCATION: Optional: lets you designate the region or multi-region where your image is stored. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

Create an image from a snapshot:

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

Replace the following:

IMAGE_NAME: a name for the new image.
SOURCE_SNAPSHOT: the snapshot from which you want to create the image.
LOCATION: Optional: flag that lets you designate the region or multi-region where your image is stored. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

View an image location:

Use the gcloud compute images describe command to view an image location.

gcloud compute images describe IMAGE_NAME

Replace IMAGE_NAME with the name of your image that you want to review.

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://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images

{
  "name": "IMAGE_NAME",
  "sourceDisk": "/zones/ZONE/disks/SOURCE_DISK",
  ("storageLocations": "LOCATION",)
  ("forceCreate": "TRUE")
}

Replace the following:

PROJECT_ID: the project to which the image belongs.
IMAGE_NAME: a name for the new image that you want to create.
ZONE: the zone where the source disk is located.
SOURCE_DISK: the disk from which you want to create the image.
LOCATION: Optional: the storage location of your image. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you don't make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

The optional forceCreate parameter lets you 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 forceCreate default setting is FALSE.

Create an image from another image:

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

{
  "name": "IMAGE_NAME",
  "sourceImage": "/global/images/SOURCE_IMAGE",
  ("storageLocations": "LOCATION")
}

Replace the following:

PROJECT_ID: the project to which the image belongs.
IMAGE_NAME: a name for the new image that you want to create.
SOURCE_IMAGE: the image from which you want to create the image.
LOCATION: Optional: the storage location of your image. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

Create an image from a snapshot:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images
{
  "name": "IMAGE_NAME",
  "sourceSnapshot": "(/SOURCE_PROJECT_ID)/global/snapshots/SOURCE_SNAPSHOT",
  ("storageLocations": "LOCATION")
}

Replace the following:

PROJECT_ID: the project to which the image belongs.
IMAGE_NAME: a name for the new image that you want to create.
SOURCE_PROJECT_ID: Optional: the project the snapshot is located in. You must have permission to access the snapshot resource in that project.
SOURCE_SNAPSHOT: the snapshot from which you want to create the image.
LOCATION: Optional: the storage location of your image. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

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

Deprecating an image

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. Use the Google Cloud Console, the gcloud command-line tool, or the Compute Engine API method to deprecate an image.

Deprecation states

The following deprecation states are supported:

ACTIVE: The image is active and can be used as normal. Image families point to the most recent and active image in a family.
DEPRECATED: The image is marked deprecated but can still be used. If you use an image that is deprecated, the request succeeds with a warning. New links to this image are allowed. Image families no longer point to this image even if it is the most recent image in the family.
OBSOLETE: The image is marked obsolete and is no longer available for use. An error message is returned if you try to use this image in a request. Existing links to this image are still allowed.
DELETED: This image is deleted. An error message is returned if you try to use a deleted image.

You can revert a deprecation (make an image active again), by changing the deprecation state to ACTIVE.

Console

In the Google Cloud Console, go to the Images page.

Go to Images
For the image you want to deprecate, click Actions.
Select Deprecate.
For state, select either Deprecated or Obsolete. For more information about states, see Deprecation states.
Optional: Specify a replacement image.
Click Deprecate Image.

gcloud

Use the gcloud compute images deprecate command to set the deprecation status of an image.

gcloud compute images deprecate IMAGE_NAME \
    --state STATE \
    --replacement REPLACEMENT

Replace the following:

IMAGE_NAME: the name of the image to deprecate
STATE: the deprecation state
REPLACEMENT: the image to replace the one that is deprecated

API

Make a POST request to the images().deprecate method. Specify the name of the image you want to deprecate.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/RESOURCE_ID/deprecate

{
  "state": "STATE",
  "replacement": "REPLACEMENT"
}

Replace the following:

PROJECT_ID: the project to which the image belongs.
RESOURCE_ID: the name of the image that you are deprecating.
STATE: the deprecation state of this resource.
REPLACEMENT: the image to replace the one that is deprecated.

Deleting an image

You can only delete custom images that you, or someone who has access to the project, have added. Use the Google Cloud Console, gcloud command-line tool, or the Compute Engine API method to delete the image.

Console

In the Google Cloud Console, go to the Images page.

Go to Images
Check the box to the left of the image you want to delete.
Click Delete at the top of the page. Your image is deleted.

gcloud

Use the gcloud compute images delete command to delete an image:

gcloud compute images delete IMAGE_NAME

Replace IMAGE_NAME with the name of the image to delete.

API

Make a POST request to the images().delete method. Specify the name of the image you want to delete.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/RESOURCE_ID

Replace the following:

PROJECT_ID: the project to which the image belongs.
RESOURCE_ID: the name of the image that you want 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 best practices when working with image families, see Image families best practices.

Optionally, you can specify the image's storage location by using the Google Cloud Console, the gcloud compute images create command with the --storage-location flag, or the images().insert method.

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

Console

In the Google Cloud Console, go to the Create an image page.

Go to Create an image
Specify the Name of your image.
Specify the Source from which you want to create an image. This can be a persistent disk, a snapshot, another image, or a disk.raw file in Cloud Storage.
Specify the Location where you will store your image. Choose your image storage location from the Based on source disk location (default) drop-down menu. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.
Specify the properties for your image. For example, you can specify the image family name my-image-family 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

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

API

Make a POST request to the images().insert method. Specify the image family in the request body.

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

{
  "name": "image-v2",
  "sourceDisk": "/zones/us-central1-f/disks/disk-2",
  "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.

gcloud

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://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v2
sourceDisk: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v2
sourceDiskId: '1677449456001963379'
sourceType: RAW
status: READY

API

Make a GET request to the images().getFromFamily method. Specify the image family in the request body.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/family

{
  "resourceId":"my-image-family",

}

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 again point to image-v1.

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

Check to make sure that the image family is pointing to image-v1.

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

family: my-image-family
id: '2741732787056801255'
kind: compute#image
name: image-v1
selfLink: https://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v1
sourceDisk: https://compute.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

Guest operating system features let you configure the following networking, security, storage, and operating system options on custom images that will also be used as boot disks:

Multi-IP subnets: For configuring interfaces with a netmask other than /32
UEFI compatibility: For booting with UEFI firmware and the following Shielded VM features:
- Secure Boot: Disabled by default.
- vTPM: Enabled by default.
- Integrity Monitoring: Enabled by default.
Multiqueue SCSI on local SSD devices as an alternative to NVMe:
- For Linux images, you can enable multiqueue SCSI on local SSD devices on images with kernel versions 3.17 and later.
- For Windows images, you can enable multiqueue SCSI on local SSD devices on images with driver version 1.2.0.1621 or later.
Windows support: You must tag Windows Server custom boot images as Windows images.

gcloud

Use the gcloud compute images create command with the --guest-os-features flag to create a new custom image from an existing custom image.

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

Replace the following:

IMAGE_NAME: the name for the new image.
SOURCE_IMAGE: an image to base the new image on.
IMAGE_PROJECT: Optional: the project containing the source image. Use this parameter to copy an image from another project.
FEATURES: IDs, separated by commas, of the guest OS features to enable for the image. Set to one or more of the following values:
- MULTI_IP_SUBNET
- UEFI_COMPATIBLE
- VIRTIO_SCSI_MULTIQUEUE
- WINDOWS
LOCATION: Optional: region or multi-region in which to store the image. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you don't make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.

API

Use the images().insert method with the guestOsFeatures flag to create a new custom image from an existing custom image.


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

{
 "name": "IMAGE_NAME",
 "sourceImage": "(projects/IMAGE_PROJECT)/global/images/SOURCE_IMAGE",
 ("storageLocations": "LOCATION",)
 "guestOsFeatures": [
  {
   "type": "FEATURES"
  }
 ]
}

Replace the following:

PROJECT_ID: the ID of the project in which to create the new image.
IMAGE_NAME: a name for the new image.
IMAGE_PROJECT: Optional: the project containing the source image. Use this parameter to copy an image from another project.
SOURCE_IMAGE: the image to base the new image on.
LOCATION: Optional: a region or multi-region in which to store the image. For example, specify us to store the image in the us multi-region, or us-central1 to store it in the us-central1 region. If you don't make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.
FEATURES: IDs, separated by commas, of guest OS features to enable for the image. Set to one or more of the following values:
- MULTI_IP_SUBNET
- UEFI_COMPATIBLE
- VIRTIO_SCSI_MULTIQUEUE
- WINDOWS

What's next

Share your private image with other projects.
Learn how to import disks, images, and VM instances.
Learn how to export an image to Cloud Storage.
Learn how to start an instance from a custom image.
Learn how to build custom base images using Jenkins and Packer.