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 root persistent disk to a certain state and would like to save that state to be reused with new instances.

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

Before you begin

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.

To create a custom image, you must first delete your instance to detach the persistent disk from the instance. Make sure you don't need the instance before you proceed.

After creating a custom image, any project editor or owner can use the image. You can also use Identity and Access Management (IAM) to share the image with other projects.

Deleting your instance

You can create images only from root disks that are not attached to an instance. Delete the instance that is using the root persistent disk, but preserve the disk so you can use it later. To delete the instance:

  1. Set the auto-delete state of the root persistent disk to false so that it is not automatically deleted when you delete the instance.

  2. Delete the instance.

  3. After the instance is deleted, create your image.

Creating the image

You can create disk images from the following sources:

  • A persistent disk that is not attached to any instances
  • Another image in your project (Beta)
  • An image that is shared from another project (Beta)
  • A compressed RAW image in Google Cloud Storage

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

Console

  1. In the Google Cloud Platform Console, go to the Create an image page.
    Go to the Create an image page
  2. Fill in the desired 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.
  3. 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]

where:

  • [SOURCE_DISK] is the disk from which you want to create the 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.

Create an image from another image:

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

where:

  • [SOURCE_IMAGE] is the image from which you want to create the 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 image belongs to.

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]",
  "sourceDisk": "zones/[ZONE]/disks/[SOURCE_DISK]"
}

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 the name of the new image that you want to create.

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:

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

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 images 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

What's next

Send feedback about...

Compute Engine Documentation