You can create custom images from source disks, images, snapshots, or images stored in Cloud Storage. You can 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:
- Install or update to the latest version of the gcloud command-line tool.
- 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 for creating a Windows image, see Creating a Windows image.
You must use Cloud Identity and Access Management (Cloud 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 beta compute
:
gcloud beta compute images describe [IMAGE_NAME] --project [PROJECT]
⋮
storageLocations:
- us-central1
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.
- Pause apps or operating system processes that write data to that persistent disk.
- Run an app flush to disk if necessary. For example, MySQL has a
FLUSH
statement. Other apps might have similar processes. - Stop your apps from writing to your persistent disk.
- 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
Console
- In the Google Cloud Console, go to the Create an image page.
Go to the Create an image page - 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 theus
multi-region, orus-central1
to store it in theus-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 beta images create
command to create a custom image. The beta
tag is required for
the optional --storage-location
flag.
Create an image from a source disk:
gcloud beta compute images create [IMAGE_NAME] \
--source-disk [SOURCE_DISK] \
--source-disk-zone [ZONE] \
--family [IMAGE_FAMILY] \
--storage-location [LOCATION] \
--force
where:
[IMAGE_NAME]
is a name for the new image.[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.[LOCATION]
is an optional flag that lets you designate the region or multi-region where your image is going to be stored. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-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.[--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 a source image:
gcloud beta compute images create [IMAGE_NAME] \
--source-image [SOURCE_IMAGE] \
--source-image-project [IMAGE_PROJECT] \
--family [IMAGE_FAMILY] \
--storage-location [LOCATION]
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.[LOCATION]
is an optional flag that allows you to designate the region or multi-region where your image is going to be stored. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-central1
region. If you do not make a selection, Compute Engine will store the image in the multi-region closest to your image's source location.
Create an image from a snapshot:
gcloud beta compute images create [IMAGE_NAME] \
--source-snapshot [SOURCE_SNAPSHOT] \
--storage-location [LOCATION]
where:
[IMAGE_NAME]
is a name for the new image.[SOURCE_SNAPSHOT]
is the snapshot from which you want to create the image.[LOCATION]
is an optional flag that allows you to designate the region or multi-region where your image is going to be stored. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-central1
region. If you do not make a selection, Compute Engine will store the image in the multi-region closest to your image's source location.
View an image location:
Use the
gcloud beta compute images describe
command to view an image location. The beta
tag is required to see
the image's storage location.
gcloud beta compute images describe [IMAGE_NAME]
where [IMAGE_NAME]
is the name of your image that you want described.
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. Use the beta
version of this
method to specify the storageLocations
parameter.
Create an image from a persistent disk:
POST https://compute.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/images
{
"name": "[IMAGE_NAME]",
"sourceDisk": "/zones/[ZONE]/disks/[SOURCE_DISK]",
"storageLocations": "[LOCATION]",
"forceCreate": "[FORCE_CREATE]"
}
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.[ZONE]
is the zone where the source disk is located.[SOURCE_DISK]
is the disk from which you want to create the image.[LOCATION]
is an optional parameter that lets you select the storage location of your image. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-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.[FORCE_CREATE]
is an optional parameter that lets you create the image from a running instance. SpecifyTRUE
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 isFALSE
.
Create an image from another image:
POST https://compute.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/images
{
"name": "[IMAGE_NAME]",
"sourceImage": "/global/images/[SOURCE_IMAGE]",
"storageLocations": "[LOCATION]"
}
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.[LOCATION]
is an optional parameter that allows you to select the storage location of your image. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-central1
region. If you do not make a selection, Compute Engine will store 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/beta/projects/[PROJECT_ID]/global/images
{
"name": "[IMAGE_NAME]",
"sourceSnapshot": "/[SOURCE_PROJECT_ID]/global/snapshots/[SOURCE_SNAPSHOT]",
"storageLocations": "[LOCATION]"
}
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.[LOCATION]
is an optional parameter that allows you to select the storage location of your image. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-central1
region. If you do not make a selection, Compute Engine will store 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 console, gcloud
command, or the Compute Engine API method to deprecate an image.
Console
- In the Google Cloud Console, go to the Create an image page.
Go to the Create an image page - Check the box to the left of the image you want to deprecate.
- Click Deprecate at the top of the page. Your image is deprecated.
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]
where, [IMAGE_NAME]
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 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. 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. Compute Engine returns an error if users attempt to use the image.
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
{
"deprecated": "[IMAGE_NAME]",
"replacement": "[REPLACEMENT]"
}
where:
[PROJECT_ID]
is the project to which the image belongs.[IMAGE_NAME]
the image you are deprecating.[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 console, gcloud
command, or the Compute Engine API method to delete the image.
Console
- In the Google Cloud Console, go to the Create an image page.
Go to the Create an image page - 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]
where [IMAGE_NAME]
is the name of the image to delete.
API
Make a POST
request to
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]
where:
[PROJECT_ID]
is the project to which the image belongs.[RESOURCE_ID]
is a name for 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.
Optionally, you can specify the
image's storage location, using the console,
the gcloud beta compute images create
command with the --storageLocation
flag, or the beta
images().insert
API 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 the Create an image page - 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 Google 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 theus
multi-region, orus-central1
to store it in theus-central1
region. If you do not make a selection, Compute Engine will store 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 beta 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 beta 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
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 the UEFI secure boot option, which restricts unsigned software from booting or unsigned drivers from loading on the VM instance. After you set this parameter, you can then enable the secure boot feature during VM instance creation.UEFI_COMPATIBLE
. Enables booting with UEFI firmware.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 later. - For Windows images, you can enable
VIRTIO_SCSI_MULTIQUEUE
on images with driver version 1.2.0.1621 or higher.
- For Linux images, you can enable
WINDOWS
. Required for Windows Server images. Newer public images for Windows Server include theWINDOWS
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
Use the gcloud compute images create
command to create a custom image from one of your existing custom images, but also
include the --guest-os-features
flag. Use the
gcloud compute beta images create
command to include
the optional --storage-location
flag.
gcloud beta compute images create [IMAGE_NAME] \
--source-image [SOURCE_IMAGE] \
--source-image-project [IMAGE_PROJECT] \
--guest-os-features="[FEATURE_ID],..." \
--storage-location [LOCATION]
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 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.[LOCATION]
is an optional flag that lets you designate the region or multi-region where your image is going to be stored. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-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
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. Use the
beta
API method for this request to see the storageLocations
parameter.
Create an image from a persistent disk:
POST https://compute.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/images
{
"name": "[IMAGE_NAME]",
"sourceImage": "projects/[IMAGE_PROJECT]/global/images/[SOURCE_IMAGE]",
"storageLocations": "[LOCATION]",
"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 image.[IMAGE_PROJECT]
is a parameter that specifies which project the source image is located in.[LOCATION]
is an optional parameter that lets you select the storage location of your image. For example, specifyus
to store the image in theus
multi-region, orus-central1
to store it in theus-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.[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 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.