Create custom images (original) (raw)

Skip to main content

Create custom images

Linux

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

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
    gcloud init
    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  2. 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.

  1. Install the Google Cloud CLI.
  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  3. 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.
    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
    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.

  1. Install the Google Cloud CLI.
  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  3. 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.
    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
    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.

  1. Install the Google Cloud CLI.
  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  3. 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.
    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
    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.

  1. Install the Google Cloud CLI.
  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  3. 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.
    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
    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.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Required roles and permissions

To get the permissions that you need to create a custom image, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to create a custom image. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create a custom image:

You might also be able to get these permissions with custom roles or other predefined roles.

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'sCloud 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 providing redundancy across regions. To create, modify, and delete images stored in Cloud Storage, you must haveroles/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 theimages describecommand from gcloud compute:

gcloud compute images describe IMAGE_NAME
--project=PROJECT_ID

Replace the following:

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:

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 prevent the disk from being automatically deleted when you delete the VM.

To disable auto-delete for the disk, use one of the following methods:

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to the VM instances page
  2. Click the name of the VM that you're using as the source for creating an image.
    The VM instance details page displays.
  3. Click Edit.
  4. In the Boot disk section, for the Deletion rule, check that the Keep disk option is selected.
  5. Click Save.

gcloud

In the Google Cloud CLI, use thegcloud compute instances set-disk-auto-delete commandto 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:

Go

Go

Before trying this sample, follow the Go setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Go API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

Java

Before trying this sample, follow the Java setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Java API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

Node.js

Before trying this sample, follow the Node.js setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Node.js API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

Python

Before trying this sample, follow the Python setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Python API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST

To set the auto-delete option of a disk, make a POST request to theinstances.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:

After you prepare the VM, create the image.

Create the image

You can create disk images from the following sources:

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, seeSnapshot frequency limits.

Console

  1. In the Google Cloud console, go to the Create an image page.
    Go to Create an image
  2. Specify the Name of your image.
  3. 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.
  4. If you are creating an image from a disk attached to a running VM, select Keep instance running to confirm that you want to create the image while the VM is running. You can prepare your VMbefore creating the image.
  5. 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 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.
  6. Optional: specify the properties for your image.
    • Family: the image familythis new image belongs to.
    • Description: a description for your custom image.
    • Label: a label to group together resources.
  7. Specify the encryption key. You can choose between a Google-owned and Google-managed encryption 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 encryption key.
  8. Click Create to create the image.

gcloud

In the Google Cloud CLI, use thegcloud compute images create commandto 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:

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:

Create an image from a snapshot:

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

Replace the following:

View an image location:

Use thegcloud compute images describe commandto 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 theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Go API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

Java

Before trying this sample, follow the Java setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Java API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

Python

Before trying this sample, follow the Python setup instructions in theCompute Engine quickstart using client libraries. For more information, see theCompute Engine Python API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST

Make a POST request to theimages().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:

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:

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:

For more information about adding images, see theimages reference.

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:

REST

Use the images().insert methodwith 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:

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 A4X, C4A, and Tau T2Amachine series, which run on Arm CPU platforms. You can start a VM with one of these 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:

Image users can then filter on this field to find x86 or Arm-based images.

What's next

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

Last updated 2026-06-18 UTC.