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. Custom images are 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 VMs.
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
- Read the Images document.
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Node.js
To use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Create a custom image
This section describes how to create a custom image on a Linux VM. For information about creating a Windows image, see Creating a Windows image.
Select 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. To create, modify, and
delete images stored in Cloud Storage, you must have
roles/compute.storageAdmin
.
The storage location feature is optional. If you don't select a location,
Compute Engine stores your image in the multi-region closest to the
image source. For example, when you create an image from a source disk that is
located in us-central1
and if you don't specify a location for the custom
image, then Compute Engine stores the image in the us
multi-region.
If the image is not available in a region where you are creating a VM, Compute Engine caches the image in that region the first time you create a VM.
To see the location where an image is stored, use the
images describe
command from gcloud compute
:
gcloud compute images describe IMAGE_NAME \ --project=PROJECT_ID
Replace the following:
IMAGE_NAME: the name of your image.
PROJECT_ID: the project ID to which the image belongs.
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 new location.
Prepare your VM for an image
You can create an image from a disk even while it is attached to a running VM. However, your image is more reliable if you put the VM in a state that is easier for the image to capture. This section describes how to prepare your boot disk for the image.
Minimize writing data to the persistent disk
Use one of the following processes to reduce the disk writes:
Stop the VM so that it can shut down and stop writing any data to the persistent disk.
If you can't stop your VM before you create the image, minimize the amount of writes to the disk and sync your file system. To minimize writing to your persistent disk, follow these steps:
- 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
.
Disable the auto-delete option for the disk
By default, the auto-delete option is enabled on the boot disks. Before creating an image from a disk, disable auto-delete to ensure that the disk is not automatically deleted when you delete the VM.Use one of the following methods to disable auto-delete for the disk.
Console
In the Google Cloud console, go to the VM instances page.
Click the name of the VM that you're using as the source for creating an image.
The VM instance details page displays.
Click Edit.
In the Boot disk section, for the Deletion rule, ensure that the Keep disk option is selected.
Click Save.
gcloud
In the Google Cloud CLI, use the
gcloud compute instances set-disk-auto-delete
command
to disable the auto-delete option for the disk.
gcloud compute instances set-disk-auto-delete VM_NAME \ --no-auto-delete \ --disk=SOURCE_DISK
Replace the following:
VM_NAME
: the name of your VM instance.SOURCE_DISK
: the name of the disk from which you want to create the image.
Go
Go
Before trying this sample, follow the Go setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Go API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
Before trying this sample, follow the Java setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Java API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Node.js
Before trying this sample, follow the Node.js setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Node.js API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
Before trying this sample, follow the Python setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Python API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
REST
To set the auto-delete option of a disk, make a POST
request to the
instances.setDiskAutoDelete
method.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setDiskAutoDelete?autoDelete=false&deviceName=SOURCE_DISK
Replace the following:
PROJECT_ID
: the project ID to which the source VM belongs.ZONE
: the zone where the source VM is located.VM_NAME
: the name of the source VM.SOURCE_DISK
: the device name of the disk from which you want to create the image.
After you prepare the VM, create the image.
Create the image
You can create disk images from the following sources:- A persistent disk, even while that disk is attached to a VM
- 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.
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.
If you are creating an image from a disk attached to a running VM, check Keep instance running to confirm that you want to create the image while the VM is running. You can prepare your VM before creating the image.
In the Based on source disk location (default) drop-down list, specify the location to store the image. 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.Optional: specify the properties for your image.
- Family: the image family this new image belongs to.
- Description: a description for your custom image.
- Label: a label to group together resources.
Specify the encryption key. You can choose between a Google-owned and Google-managed key, a Cloud Key Management Service (Cloud KMS) key or a customer- supplied encryption (CSEK) key. If no encryption key is specified, images are encrypted using a Google-owned and Google-managed key.
Click Create to create the image.
gcloud
In the Google Cloud CLI, 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 imageSOURCE_DISK
: the disk from which you want to create the imageZONE
: the zone where the disk is locatedIMAGE_FAMILY
: Optional: a flag that specifies which image family this image belongs toLOCATION
: Optional: a flag that lets you designate the region or multi-region where your image is 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.
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, 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.
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 imageSOURCE_SNAPSHOT
: the snapshot from which you want to create the imageLOCATION
: Optional: a flag that lets you designate the region or multi-region where your image is 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.
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.
Go
Go
Before trying this sample, follow the Go setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Go API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
Before trying this sample, follow the Java setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Java API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
Before trying this sample, follow the Python setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Python API reference documentation.
To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
REST
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 ID 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, 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.
The optional forceCreate
parameter lets you create the image from a
running VM. Specify TRUE
only if you are sure that you want to
create the image from a running VM. 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, 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.
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, 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.
For more information about adding images, see the images reference.
Share the image
After creating a custom image, you can share it across projects. If you allow users from another project to use your custom images, then they can access these images by specifying the image project in their request.
Enable guest operating system features
Use guest operating system (OS) features to configure the following networking, security, storage, and OS options on custom images. Custom images with these configured features are used as boot disks.
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 imageSOURCE_IMAGE
: an image to base the new image onIMAGE_PROJECT
: Optional: the project containing the source imageUse this parameter to copy an image from another project.
FEATURES
: guest OS tags to enable features for VMs that you create from imagesTo add multiple values, use commas to separate values. Set to one or more of the following values:
-
VIRTIO_SCSI_MULTIQUEUE
. Use on local SSD devices as an alternative to NVMe. For more information about images that support SCSI, see Choosing an interface.For Linux images, you can enable multi-queue SCSI on local SSD devices on images with kernel versions 3.17 or later. For Windows images, you can enable multi-queue SCSI on local SSD devices on images with Compute Engine Windows driver version 1.2.
-
WINDOWS
. Tag Windows Server custom boot images as Windows images. -
MULTI_IP_SUBNET
. Configure interfaces with a netmask other than/32
. For more information about multiple network interfaces and how they work, see Multiple network interfaces overview and examples. -
UEFI_COMPATIBLE
. Boot with UEFI firmware and the following Shielded VM features:- Secure Boot: disabled by default
- Virtual Trusted Platform Module (vTPM): enabled by default
- Integrity monitoring: enabled by default
-
GVNIC
. Support higher network bandwidths of up to 50 Gbps to 100 Gbps speeds. For more information, see Using Google Virtual NIC. -
IDPF
. Support Intel Infrastructure Data Path Function (IDPF) network interfaces. -
SEV_CAPABLE
orSEV_SNP_CAPABLE
. Use these tags if you want to use your image on a Confidential VM instance with AMD Secure Encrypted Virtualization (SEV) or AMD Secure Encrypted Virtualization-Secure Nested Paging (SEV-SNP) support. To check if your kernel supports AMD SEV or AMD SEV-SNP, see Linux kernel details. -
SEV_LIVE_MIGRATABLE_V2
. Use this tag if you want to use your image on a Confidential VM instance that supports live migration on AMD SEV. To check if your kernel supports live migration, see Linux kernel details. -
TDX_CAPABLE
. Use this tag if you want to use your image on a Confidential VM instance with Intel Trust Domain Extensions (TDX) support. To check if your kernel supports Intel TDX, see Linux kernel details.
-
-
SUSPEND_RESUME_COMPATIBLE
. Support suspend and resume on a VM. For more information, see OS compatibility.
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.
REST
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 imageIMAGE_NAME
: a name for the new imageIMAGE_PROJECT
: Optional: the project containing the source imageUse this parameter to copy an image from another project.
SOURCE_IMAGE
: the image to base the new image onLOCATION
: Optional: a region or multi-region in which to store the imageFor 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.FEATURES
: guest OS tags to enable features for VMs that you create from imagesTo add multiple values, use commas to separate values. Set to one or more of the following values:
-
VIRTIO_SCSI_MULTIQUEUE
. Use on local SSD devices as an alternative to NVMe. For more information about images that support SCSI, see Choosing an interface.For Linux images, you can enable multi-queue SCSI on local SSD devices on images with kernel versions 3.17 or later. For Windows images, you can enable multi-queue SCSI on local SSD devices on images with Compute Engine Windows driver version 1.2.
-
WINDOWS
. Tag Windows Server custom boot images as Windows images. -
MULTI_IP_SUBNET
. Configure interfaces with a netmask other than/32
. For more information about multiple network interfaces and how they work, see Multiple network interfaces overview and examples. -
UEFI_COMPATIBLE
. Boot with UEFI firmware and the following Shielded VM features:- Secure Boot: disabled by default
- Virtual Trusted Platform Module (vTPM): enabled by default
- Integrity monitoring: enabled by default
-
GVNIC
. Support higher network bandwidths of up to 50 Gbps to 100 Gbps speeds. For more information, see Using Google Virtual NIC. -
IDPF
. Support Intel Infrastructure Data Path Function (IDPF) network interfaces. -
SEV_CAPABLE
orSEV_SNP_CAPABLE
. Use these tags if you want to use your image on a Confidential VM instance with AMD Secure Encrypted Virtualization (SEV) or AMD Secure Encrypted Virtualization-Secure Nested Paging (SEV-SNP) support. To check if your kernel supports AMD SEV or AMD SEV-SNP, see Linux kernel details. -
SEV_LIVE_MIGRATABLE_V2
. Use this tag if you want to use your image on a Confidential VM instance that supports live migration on AMD SEV. To check if your kernel supports live migration, see Linux kernel details. -
TDX_CAPABLE
. Use this tag if you want to use your image on a Confidential VM instance with Intel Trust Domain Extensions (TDX) support. To check if your kernel supports Intel TDX, see Linux kernel details.
-
-
SUSPEND_RESUME_COMPATIBLE
. Support suspend and resume on a VM. For more information, see OS compatibility.
Avoid sensitive information in UEFI variables
Unified Extensible Firmware Interface (UEFI) variables are key-value pair variables used by the UEFI firmware during boot time to boot the operating system of a VM. Unlike physical machines, where the variables are stored on a hardware chip, Compute Engine virtualizes storage of these variables. As such, in many operating systems, all applications and users can reach these variables and access this information.
Because of this reason, Google strongly recommends that you don't write or store sensitive or personal identifiable information such as passwords or private keys to UEFI variables.
Considerations for Arm images
Google offers the Tau T2A machine series, which runs on the Ampere Altra CPU platform. You can start a VM with the T2A machine series and then use that source VM to create an Arm image. The process for creating a custom Arm image is identical to creating an x86 image.
To help your users differentiate between Arm and x86 images, Arm images will
have an architecture
field set to ARM64
. Possible values for this
field are:
ARCHITECTURE_UNSPECIFIED
X86_64
ARM64
Image users can then filter on this field to find x86 or Arm-based images.
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 a VM from a custom image.
- Learn how to set the image version in an image family.
- Learn how to deprecate a custom image.
- Learn how to delete a custom image.