Hide
Compute Engine

Images

An Image resource contains a boot loader, an operating system and a root file system that is necessary for starting an instance. You must always specify an image when you create an instance or when you create a root persistent disk. By default, Google Compute Engine will always install the root file system defined by the image on a root persistent disk.

Images belong to a project and can be accessible by that project as a private image or accessible by any project as a public image. The project owner controls how accessible the image is. Depending on the contents of the image, some images cost money to use, while others are available free of charge. For example, Google-provided images of Red Hat Enterprise Linux (RHEL) and SUSE cost an additional fee to use.

This page describes the Image resource in detail, how to create an image from a root persistent disk, and how to import images from other sources.

For advanced users, you can also build your own image.

Contents

Accessing images

Images can be either public or private. Public images are available to all users, while private images are only available to the project that the image resides in. Access to an image depends on whether an image is public or private and whether you have the right permissions.

Public images

Public images are visible by everybody and can be used by any Compute Engine project. Public images are provided and maintained by Google, open-source communities, and third-party vendors. These images contain preloaded operating systems that can run on Compute Engine instances.

It is currently not possible for users to create public images. If you want to share an image, you should instead grant access to where the original source image file is stored and then direct others to Import the image to their own projects.

Private images

By default, any images you create are private images that are only accessible by the project where the image originated. You can create a new private image from an existing root persistent disk or you can build a new private image from scratch.

List all images

You can see a list of all images available to your project using gcloud compute with the images list command.

$ gcloud compute images list

This lists both private and public images that are available to your project. To differentiate between the images, refer to the Project column in the gcloud compute output, which indicates which project each image belongs to.

Start an instance from a public image

The steps for using a public image differs if you are using gcloud compute or using the API.

gcloud


To use an image in gcloud compute, you can either provide the fully-qualified URL to a specific image, use alias matching to select the latest public image offered by Compute Engine, or provide the image name with the image project.

Alias matching is the most convenient way to ensure that you are using the latest version of an image. For example, the debian-7 alias will always pick the latest version of the Debian 7 image. This keeps you from having to keep track of the version numbers for images. Not all images have an alias. For a comprehensive list of valid aliases, see the operating systems documentation or the reference page for gcloud compute instances create.

When you provide an alias as part of your request, gcloud compute will also look in your personal project for an exact match to the flag value. If there are multiple matching entries, gcloud compute prompts you to select one. Otherwise, gcloud compute will use the latest version of the image from the corresponding image project. For example, the following request uses alias matching to select the latest Debian 7 image from the debian-cloud project:

$ gcloud compute instances create example-instance --image debian-7

If you provide an image name that does not match any of the aliases, gcloud compute assumes that the image is a private image from your project.

When you want to use a specific image version, provide the image name with the image project. For example, to use a Debian image, make a request like so:

$ gcloud compute instances create INSTANCE --image debian-7-wheezy-vYYYYMMDD \
         --image-project debian-cloud

If you prefer to use an image URL, you can also provide a URL to the specific image:

$ gcloud compute instances create INSTANCE \
         --image https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-vYYYYMMDD

API


In the API, you must provide the full URL to your desired image in your request. A fully-qualified URL uses the following format:

https://www.googleapis.com/compute/v1/projects/centos-cloud/global/images/centos-6-vYYYYMMDD

For more information, see the API reference.

Start an instance from a private image

The steps for using a private image differs if you are using gcloud compute or using the API.

gcloud


You can start an instance from a private image by providing the image name:

$ gcloud compute instances create example-instance --image my-private-image

Notice that you do not need the fully-qualified URL to the private image, as gcloud compute will look in your project for the image automatically.

API


In the API, you must provide the fully-qualified URL or a valid partial URL to your private image in your request. A fully-qualified URL uses the following format:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/images/my-private-image

Alternatively, Compute Engine can also infer your project ID, API version, and API name automatically, so you can use a partial URL as well, such as:

global/images/my-private-image

Both partial and full URLs are valid. For more information, see the API reference.

Create an image from a root persistent disk

These instructions describe how to create a new private image from an existing persistent disk. This is ideal for situations where you might have created and then modified a persistent boot disk to a certain state and would like to save that state to be reused.

To create a new image:

  1. Start a new instance and log in.
  2. Customize your instance by adding packages, configuring startup daemons, and so on.
  3. Terminate your instance to create your image.
  4. Create a new image of your instance using gcloud compute images create.

Follow these steps below.

  1. Start a new instance or log in to an existing instance.

    Review the details about starting a new instance if you need to create a new instance. Start a new instance as follows, replacing IMAGE with an image of your choice, such as debian-7:

    $ gcloud compute instances create example-instance --image IMAGE
    

    ssh into your instance:

    $ gcloud compute ssh example-instance
    
  2. Customize your instance.

    Customize your instance as you like. The following example demonstrates logging in and installing Apache on an instance:

    $ gcloud compute ssh example-instance
    ...snip ssh startup info...
    me@example-instance:~$ sudo apt-get install apache2
    ...snip installation process...
    
  3. Terminate your instance.

    Before you can create your image, you must terminate the instance using the persistent disk and make sure the persistent disk is not attached to any other virtual machines.

    1. (Windows only) sysprep your instance

      On a Windows virtual machine, you must first sysprep your instance before you can make an image of it. The sysprep process terminates your instance so make sure you have saved your data before starting this process.

      Once you are ready, start the sysprep process using the sysprep instructions.

    2. Next, terminate your instance but retain your boot persistent disk using the gcloud compute instances delete command:

      $ gcloud compute instances delete example-instance --keep-disks boot
      
  4. Add your image.

    When you are ready to create your new image, use the gcloud compute with the images create, and provide the source persistent disk to make an image of.

    $ gcloud compute images create example-image --source-disk example-disk --source-disk-zone ZONE
    

    When you run this command, gcloud compute creates a new image based on the persistent disk you provided and adds it to your collection. You can confirm that your image was successfully created by running:

    $ gcloud compute images list
    

    For more information about adding images, see the images reference.

Import an image

In addition to any of the images already available on Compute Engine, you can also choose to import an image you already have into Compute Engine. This section provides general information on how to import images from different sources.

Import a RAW image

You can import a RAW image file into Compute Engine and use it to create new instances. In order to import a RAW file, the file must fulfill the following requirements:

  • The RAW file must be named disk.raw.
  • The RAW file must be packaged as a gzipped tar file with the tar.gz file extension. For example, you can package a RAW file using the tar command:

    $ tar -Sczf example-image.tar.gz disk.raw
    
  • The file must be stored in Google Cloud Storage.

To add a RAW image to your project, add the tar file containing the disk.raw image to your images list. In gcloud compute, run the following:

$ gcloud compute images create IMAGE_NAME --source-uri URI

You must choose an image name that is unique among all images in the project and provide the URI of your tar file in Google Cloud Storage, using either of the URI scheme shown below:

  • gs://BUCKET_NAME/IMAGE_NAME.image.tar.gz
  • https://storage.googleapis.com/BUCKET_NAME/IMAGE_NAME.image.tar.gz

You can check if the image is ready to use by performing a images describe command, which returns the image state as well. After the image is READY, you can use it for your instances.

When you add an image, Google Compute Engine makes a private copy of the image to use. Any changes that you make the original Google Cloud Storage object won't affect the image used by Google Compute Engine.

Once you have successfully added the image to Compute Engine, you can use to it start new instances.

Import an Amazon Machine Image

You can import an Amazon Machine Image (AMI) to Compute Engine and use the image to start a new Compute Engine virtual machine. This lets you move between cloud providers without recreating your virtual machines from scratch.

These instructions assume the following:

  • You are familiar with Amazon EC2.
  • You have an account with Amazon Web Services (AWS).
  • You have an Amazon EC2 instance currently running an image based on the Ubuntu 14.04 AMI.

These instructions are provided as general guidance for importing Ubuntu 14.04 images, but can be used for other Linux distributions. The steps for this process are:

  1. SSH into your instance and prepare instance for migration.
  2. Use the AMI tools to bundle up the Amazon EBS volume.
  3. Repackage the image for Compute Engine.
  4. Download the Google Cloud SDK.
  5. Upload the new image format to Google Cloud Storage and import it into Compute Engine.

Depending on your virtual machine setup, these steps may differ.

  1. SSH into the instance with the standard ubuntu user and switch to root. For example:

    $ ssh -i KEY_FILE.pem ubuntu@x.x.x.x
    $ sudo su -
    
  2. [Optional] Disable cloud.init to speed up boot-up time. Run the following commands:

    $ cd /etc/init
    $ for f in $(ls cloud*.conf)
    do
    newname=$(basename -s .conf $f)
    echo manual > $newname.override
    done
    
  3. [Recommended] For optimal performance and security on Compute Engine, we recommend that you add the following files to the /etc/sysctl.d/ directory. Make sure to keep the names of the files are they are shown here:

  4. Set a hosts entry for the Compute Engine metadata server:

    $ cat >> /etc/hosts <<EOF
    169.254.169.254    metadata.google.internal metadata
    EOF
    
  5. Edit /etc/rc.local to set the hostname at boot, so that the instance boots with the name you give the instance in Compute Engine:

    $ cat > /etc/rc.local <<EOF
    #!/bin/sh -e
    curl --silent --max-time 10 --connect-timeout 3 \
    -H "Metadata-flavor: Google" \
    http://metadata/computeMetadata/v1/instance/hostname | \
    awk -F. '{print $1}' > /etc/hostname
    exit 0
    EOF
    
  6. Install the following dependencies:

    $ apt-get install kpartx grub
    
  7. Create a temporary build directory to store key and build files:

    $ mkdir /tmp/build
    
  8. Create a grub config that works on Compute Engine:

    $ cat > /tmp/build/menu.lst <<EOF
    default     0
    timeout     0
    hiddenmenu
    title       Ubuntu 14.04.1 LTS, kernel 3.13.0-36-generic
    root        (hd0)
    kernel      /boot/vmlinuz-3.13.0-36-generic root=/dev/sda1 ro console=ttyS0
    initrd      /boot/initrd.img-3.13.0-36-generic
    EOF
    
  9. Create an fstab that works on Compute Engine:

    $ cat > /tmp/build/fstab <<EOF
    /dev/sda1 / ext4 defaults 1 1
    EOF
    
  10. Generate an X.509 certificate and download the corresponding certificate (cert-<hash>.pem) and private key (pk-<hash>.pem) files to your local computer.

  11. Copy the two files to your instance from your local computer. You can do this in multiple ways. For example, you can copy the files using scp on your local computer, where x.x.x.x represents your EC2 instance's external IP address:

    $ scp -i KEY_FILE.pem cert-<hash>.pem pk-<hash>.pem ubuntu@x.x.x.x:~
    

    On your instance, move the files to the /tmp/build folder:

    root@x.x.x.x:~$ mv /home/ubuntu/cert-<hash>.pem /home/ubuntu/pk-<hash>.pem /tmp/build
    
  12. Find and note your Amazon account Id on the Account Settings console.

  13. On your Amazon EC2 instance, download and install the EC2 AMI tools.

  14. Run the ec2-bundle-vol as root with the following arguments, replacing cert-<hash>.pem with the certificate file, pk-<hash>.pem with the private key, and AWS_ACCOUNT_ID with your Amazon account ID:

    $ ec2-bundle-vol -c /tmp/build/cert-<hash>.pem \
    -k /tmp/build/pk-<hash>.pem -u AWS_ACCOUNT_ID \
    -r x86_64 --no-filter --exclude /tmp/build \
    --grub-config /tmp/build/menu.lst \
    --fstab /tmp/build/fstab
    
  15. Download, install, and authenticate the Google Cloud SDK:

    $ curl https://sdk.cloud.google.com | bash
    

    Authenticate the tool using:

    $ ~/google-cloud-sdk/bin/gcloud auth login
    

    Optionally, you can also set your default Google Developers Console project after authenticating:

    $ ~/google-cloud-sdk/bin/gcloud config set project PROJECT
    
  16. Create a new Google Cloud Storage bucket:

    $ ~/google-cloud-sdk/bin/gsutil mb gs://BUCKET_NAME
    
  17. Create a sparse tarball and upload it to your new bucket, replacing BUCKET_NAME with the name of the Google Cloud Storage bucket you created:

    $ cd /tmp/
    $ mv image disk.raw
    $ tar -Sczf aws-image.tar.gz disk.raw
    $ ~/google-cloud-sdk/bin/gsutil cp aws-image.tar.gz gs://BUCKET_NAME
    
  18. Import the image into Compute Engine:

    $ ~/google-cloud-sdk/bin/gcloud compute images create aws-ubuntu \
      --source-uri gs://BUCKET_NAME/aws-image.tar.gz
    

Great! Now that you have imported your image into Compute Engine, you can start a new instance.

To ssh into an instance created using this image, you will need to use the private ssh key that was generated by Amazon when you created your original Amazon EC2 instance. In the following example, replace x.x.x.x with the external IP of your instance and KEY_FILE.pem with the private key file to log into your new instance:

$ ssh -i KEY_FILE.pem ubuntu@x.x.x.x


Amazon Web Services, Amazon EC2, and Amazon EBS are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.

Import a VirtualBox image

You can import a VirtualBox image to Compute Engine. This allows you to build an image from scratch and test it locally before you use it to create Compute Engine virtual machine instances.

These instructions assume the following:

To import a VirtualBox guest image to Compute Engine:

  1. Shut down the VirtualBox guest machine that you want to import. You can shut down the guest machine with the VirtualBox interface or the VBoxManage utility.

    $ VBoxManage controlvm GUEST_NAME acpipowerbutton
    
  2. Convert the guest image to RAW format with the VBoxManage utility:

    $ VBoxManage clonehd /path/to/guest-image.vdi \
    ~/disk.raw --format RAW
    
  3. Download, install, and authenticate the Google Cloud SDK:

    $ curl https://sdk.cloud.google.com | bash
    

    Authenticate the tool using:

    $ ~/google-cloud-sdk/bin/gcloud auth login
    

    Optionally, you can also set your default Google Developers Console project after authenticating:

    $ ~/google-cloud-sdk/bin/gcloud config set project PROJECT
    
  4. Create a new Google Cloud Storage bucket:

    $ ~/google-cloud-sdk/bin/gsutil mb gs://BUCKET_NAME
    
  5. Create a sparse tarball and upload it to your new bucket:

    $ tar -Sczf vbox-image.tar.gz disk.raw
    $ ~/google-cloud-sdk/bin/gsutil cp vbox-image.tar.gz gs://BUCKET_NAME
    
  6. Import the image into Compute Engine:

    $ ~/google-cloud-sdk/bin/gcloud compute images create vbox-ubuntu \
      --source-uri gs://BUCKET_NAME/vbox-image.tar.gz
    

You can select this image when you create new Compute Engine virtual machines.

Export an image to Google Cloud Storage

You can export a custom image as backup or for sharing by exporting the image as a tar file to Google Cloud Storage. By default, many publicly-available Compute Engine images provide the gcimagebundle tool, which can create the tar.gz file for you.

To create and export an image:

  1. Create a non-root persistent disk to hold your tar file.

    You can detach and delete the disk afterwards.

    $ gcloud compute disks create temporary-disk --zone ZONE
    
  2. Start a new instance or log in to an existing instance.

    Review the details about starting a new instance if necessary. Start a new instance as follows:

    $ gcloud compute instances create example-instance --scopes storage-rw \
             --image IMAGE \
             --disk name=temporary-disk device-name=temporary-disk \
             --zone ZONE
    

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

    If you are using an existing instance, you can attach the temporary disk like so:

    $ gcloud compute instances attach-disk example-instance --disk temporary-disk \
             --device-name temporary-disk \
             --zone ZONE
    
  3. ssh into your instance:

    $ gcloud compute ssh example-instance
    
  4. Determine where you data disk lives.

    $ ls -l /dev/disk/by-id/google-*
    lrwxrwxrwx 1 root root  9 Jul 29 17:56 /dev/disk/by-id/google-persistent-disk-0 -> ../../sda
    lrwxrwxrwx 1 root root 10 Jul 29 17:56 /dev/disk/by-id/google-persistent-disk-0-part1 -> ../../sda1
    lrwxrwxrwx 1 root root  9 Aug 25 18:16 /dev/disk/by-id/google-temporary-disk -> ../../sdb # Temporary disk lives on /dev/sdb
    
  5. Format and mount your new disk

    $ sudo mkdir /mnt/tmp
    $ sudo /usr/share/google/safe_format_and_mount -m "mkfs.ext4 -F" /dev/sdb /mnt/tmp
    
  6. Create a tar file of your image.

    When you are finished customizing your OS, create an image and bundle it into a .tar.gz file. The gcimagebundle tool included in Google Compute Engine images will create a tar file of the instance for you. The image is stored as a raw block file, packaged and compressed using gzip and tar. The raw block file contains the OS and all installed packages, plus all files in the root persistent disk. It does not include files or packages in a non-root persistent disk.

    The gcimagebundle tool can be accessed by calling gcimagebundle on instances created from Google-provided images. For help, call python gcimagebundle --help

    To save an image of your instance, run the following command:

    me@example-instance:~$ sudo gcimagebundle \
       -d /dev/sda -o /mnt/tmp/ --log_file=/tmp/abc.log
    

    This command will create an image of the instance in the following location:

    /mnt/tmp/HEX-NUMBER.image.tar.gz
    
  7. Upload an image into Google Cloud Storage

    To upload the tar file to Google Cloud Storage, use the gsutil command line tool that comes preinstalled on your instance.

    1. Create a bucket using gsutil.

      Make sure to review the Bucket and Naming Guidelines before you create your bucket. Then, create your bucket using the following command:

      me@example-instance:~$ gsutil mb gs://BUCKET_NAME
      

      You must enable billing for your Google Cloud Storage account before you can use the Google Cloud Storage service. To understand how Google Cloud Storage bills for usage, see their pricing table.

    2. Copy your file to your new bucket.

      me@example-instance:~$ gsutil cp /mnt/tmp/IMAGE_NAME.image.tar.gz gs://BUCKET_NAME
      

That's it, you have exported your file into Google Cloud Storage. You can now share the image with other people, or use the tar file to add a new image to a Google Developers Console project.

Deprecate an image

Google Compute Engine lets you deprecate a private 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 in gcloud compute, use the images deprecate subcommand, replacing IMAGE with the name of the image to deprecate:

$ gcloud compute images deprecate IMAGE --state STATE --replacement REPLACEMENT

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 an warning. New links to this image are still allowed.
  • 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.

Delete an image

You can only delete private images that you or someone who has access to the project has added. To delete an image using the images delete, run the following command, replacing IMAGE with the name of the image to delete:

$ gcloud compute images delete IMAGE