Export a custom image to Cloud Storage

If you need to move your Compute Engine boot disk data outside of your Compute Engine project, you can export a boot disk image to Cloud Storage as a tar.gz file. If you need to create a persistent disk image to use when you create new persistent disks on Compute Engine, read Creating a custom image.

You can backup or share a custom image by exporting the image to Cloud Storage. This method is ideal for sharing individual images with projects that do not have access to your images. Alternatively, you can share images by granting the Compute Engine image user role on the image or on the project that contains it.

The following diagram shows some typical workflows for the creation and reuse of a custom image.

Before you begin

• Read the images page.
• If the project that you want to export the image from has a trusted image policy defined, add projects/compute-image-import and projects/compute-image-tools to the allowed list of publishers.
• To find out how to meet requirements before exporting images, see Prerequisites for importing and exporting VM images.
• 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

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

  2. Set a default region and zone.

  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.

Limitations and restrictions

For projects that are protected with VPC Service Controls, use one of the following methods:

• export from the same project where the image resides
• export the image manually

Export an image with a single command

Export an image to Cloud Storage

You can export your images using either the Google Cloud console, the Google Cloud CLI, or REST.

gcloud compute images export \
    --destination-uri DESTINATION_URI \
    --image IMAGE_NAME

gcloud compute images export \
    --destination-uri gs://my-bucket/my-image.tar.gz \
    --image my-image \
    --project my-project

POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
{
  "timeout": "7200s",
  "steps":[
    {
      "args":[
        "-timeout=7000s",
        "-source_image=SOURCE_IMAGE",
        "-client_id=api",
        "-format=IMAGE_FORMAT",
        "-destination_uri=DESTINATION_URI"
      ],
      "name":"gcr.io/compute-image-tools/gce_vm_image_export:release",
      "env":[
        "BUILD_ID=$BUILD_ID"
      ]
    }
  ],
  "tags":[
    "gce-daisy",
    "gce-daisy-image-export"
  ]
}

{
"name": "operations/build/myproject-12345/operation-1578608233418",
"metadata": {
 "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
 "build": {
  "id": "3a2055bc-ccbd-4101-9434-d376b88b8940",
  "status": "QUEUED",
  "createTime": "2019-10-02T18:59:13.393492020Z",
  "steps": [
   {
    "name": "gcr.io/compute-image-tools/gce_vm_image_export:release",
    "env": [
     "BUILD_ID=3a2055bc-ccbd-4101-9434-d376b88b8940"
    ],
    "args": [
     "-timeout=7056s",
     "-source_image=my-image",
     "-client_id=api",
     "-format=vmdk",
     "-destination_uri=gs://my-bucket/my-exported-image.vmdk"
    ]
   }
  ],
  "timeout": "7200s",
  "projectId": "myproject-12345",
  "logsBucket": "gs://123456.cloudbuild-logs.googleusercontent.com",
  "options": {
   "logging": "LEGACY"
  },
  "logUrl": "https://console.cloud.google.com/cloud-build/builds/3a2055bc-ccbd-4101-9434-d376b88b8940?project=123456"
 }
 }

Export an image from a project using a custom Compute Engine service account

During an image export, a temporary virtual machine (VM) instance is created in your project. The image export tool on this temporary VM must be authenticated.

A service account is an identity that is attached to a VM. Service account access tokens can be accessed through the instance metadata server and used to authenticate the image export tool on the VM.

By default, the export process uses the project's default Compute Engine Service Agent. However, if the default Compute Engine service account is disabled in your project or if you want to use a custom Compute Engine service account, then you need to create a service account and specify it for the export process.

You can export your images using either the Google Cloud CLI, or REST.

gcloud compute images export \
    --destination-uri gs://my-bucket/my-image.tar.gz \
    --image my-image \
    --project my-project \
    --compute-service-account image-export-service-account@proj-12345.iam.gserviceaccount.com
    

Export an image using Shared VPC

Before you export an image that uses a shared VPC, you must add the compute.networkUser role to the Cloud Build service account. For more information, see Grant required roles to the Cloud Build service account.

You can export your image using either the Google Cloud CLI, or the REST.

gcloud compute images export \
    --image IMAGE_NAME \
    --destination-uri DESTINATION_URI \
    --project PROJECT_ID \
    --network NETWORK \
    --subnet SUBNET \
    --zone ZONE

gcloud compute images export \
    --image example-image \
    --destination-uri gs://my-bucket/my-image.tar.gz \
    --project my-project \
    --network projects/my-vpc-project/global/networks/my-shared-vpc \
    --subnet projects/my-vpc-project/regions/us-west1/subnetworks/my-custom-subnet \
    --zone us-west1-c
 

Create and export an image manually

If the gcloud compute images create and gcloud compute images export commands do not meet your requirements, you can create and export an image manually from a Compute Engine instance. This process has discrete steps to first create an image and then export an image.

In the following example, note the created disk is called image-disk.

To create and export an image:

1. Optional: Stop the instance that the disk is attached to before you create the snapshot. Stopping the instance ensures the integrity of the disk contents in the snapshot.

2. Create a snapshot of the disk. Name the snapshot image-snapshot.

   gcloud compute disks snapshot DISK_NAME \
       --snapshot-names image-snapshot

   Replace DISK_NAME with the name of the disk that you want to use to create the snapshot. You can find the name of the disk by listing disks.

3. Use the image-snapshot snapshot to create a new disk named image-disk by running the following command:

   gcloud compute disks create image-disk \
       --source-snapshot image-snapshot

4. Create a temporary disk named temporary-disk to hold your tar file, and specify the SIZE of the disk to be at least 50% larger than the image disk.

   You can detach and delete the disk afterwards.

   gcloud compute disks create temporary-disk \
       --size SIZE

   where SIZE is the size, in gigabytes or terabytes, of the temporary disk. For example, specify 100GB to create a 100-gigabyte disk.

5. Create an instance and enable storage-rw scope on the instance. Also, attach the image-disk and the temporary-disk to the instance as secondary disks with specific device-name attributes. Replace VM_NAME with the name of the instance to create.

   gcloud compute instances create VM_NAME \
       --scopes storage-rw \
       --disk name=image-disk,device-name=image-disk \
       --disk name=temporary-disk,device-name=temporary-disk

   Note that you're passing in service account scopes so that you can upload your file to Cloud Storage in later steps.

   Review the details about starting a new instance if necessary.

6. Connect to your instance. Replace VM_NAME with the name of the instance to connect to.

   gcloud compute ssh VM_NAME

7. Format and mount the temporary disk. Formatting the disk deletes the contents of the temporary disk.

   sudo mkdir /mnt/tmp

   sudo mkfs.ext4 -F /dev/disk/by-id/google-temporary-disk

   sudo mount -o discard,defaults /dev/disk/by-id/google-temporary-disk /mnt/tmp

8. Optional: Mount the image disk and make additional changes before you create the tar file. For example, you might want to delete any existing files from the /home directory if you do not want them to be part of your image. Mount the disk partitions that you need to modify, modify the files on the disk that you need to change, and then unmount the disk when you are done.

   1. Create a directory where you can mount your disk or partition.

      sudo mkdir /mnt/image-disk

   2. Use the ls command to determine which disk or disk partition you need to mount.

      ls /dev/disk/by-id/

      The command prints a list of disk IDs and partitions. For example, the following disk has a partition table with one partition. The google-image-disk ID points to the full disk from which you want to create an image. The google-image-disk-part1 ID points to the first partition on this disk. Mount the partition if you need to make changes to the disk, then create the image from the full disk.

      google-image-disk
      google-image-disk-part1
      

   3. Mount the disk or the partition. If your disk has a partition table, mount the individual partitions for your disk. For example, mount google-image-disk-part1.

      sudo mount /dev/disk/by-id/google-image-disk-part1 /mnt/image-disk

      Alternatively, if your disk is raw formatted with no partition table, mount the full google-image-disk disk.

      sudo mount /dev/disk/by-id/google-image-disk /mnt/image-disk

   4. Modify the files in the /mnt/image-disk directory to configure the files on the disk. As an example, you might remove the /mnt/image-disk/home/[USER]/.ssh/authorized_keys file to protect your SSH keys from being shared.

   5. After you have finished modifying files, unmount the disk.

      sudo umount /mnt/image-disk/

9. Create a tar file of your image.

   When you finish customizing the files on the image disk, create a raw disk file on your temporary disk. The name of the raw disk image must be 'disk.raw':

    sudo dd if=/dev/disk/by-id/google-image-disk of=/mnt/tmp/disk.raw bs=4096

   Then create the tar.gz file:

   cd /mnt/tmp

   sudo tar czvf myimage.tar.gz disk.raw

   This command creates an image of the instance in the following location:

   /mnt/tmp/myimage.tar.gz

10. Upload the image into Cloud Storage.

    To upload the tar file to Cloud Storage, use the Google Cloud CLI that comes preinstalled on your instance.

    1. Create a bucket using the gcloud CLI.

       Make sure to review the bucket and object naming guidelines before you create your bucket. Then, create your bucket using the following command. Replace BUCKET_NAME with the name of the bucket to create.

       me@example-instance:~$ 
       gcloud storage buckets create gs://BUCKET_NAME

    2. Copy your file to your new bucket. Replace BUCKET_NAME with the name of the bucket to copy the file to.

       me@example-instance:~$ 
       gcloud storage cp /mnt/tmp/myimage.tar.gz gs://BUCKET_NAME

You have exported your file into Cloud Storage. You can now share the image with other people, or use the tar file to add a new image to a Google Cloud console project.

What's next

• Share images using the image user role.
• Learn about the import methods available for Compute Engine.