Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



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 either 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 create a new image altogether.

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. Users who want to share an image publicly should grant public access to the original Google Cloud Storage bucket where the source image file is stored.

Private images

Users create private images by default. Private images are only accessible from the project that owns the image. As a user, you can create a new image from an existing root persistent disk or you can create a new image from. scratch. To create a private image, see Creating an image from a root persistent disk .

Listing all images

You can see a list of all images available to your project using gcloud compute with the images list command. This lists all public and private images that your project can use. 

$ gcloud compute images list

Starting an instance from an image

Using an image differs if you are using gcloud compute or using the API.

Starting an instance in gcloud

To use an image in gcloud compute , you can either provide the fully-qualified URL to a specific image for private images or use prefix matching to use the latest public image offered by Compute Engine. To use prefix matching, provide one of the following values with your --image flag in gcloud compute :

For example, if you pass in --image debian-7 , gcloud compute looks in the debian-cloud project to perform prefix matching and also looks 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. A request to add an instance using prefix matching looks like the following: 

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

Image projects are named according to the image type. The Debian image project is named debian-cloud , the CentOS project is named centos-cloud , and so on for other images.

To use a specific version of an image in your requests, provide the exact 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 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. To avoid the possibility or gcloud compute prompting you for an image, such as scenarios where you are scripting the tool, do not create images with names that match the aliases above.

Starting an instance in the API

In the API, prefix matching does not occur and you must provide the full URL to your desired image in your request. For example, to create a root persistent disk in the API, you must provide the sourceImage query parameter with the full URI to your desired image, like so: 

https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/disks?sourceImage=<image-url>

<image-url> must have the following format. As an example, this URL points to a Centos image: 

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

For more information, see the API reference .

Creating 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. 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: 

    $ gcloud compute instances create example-instance --scopes storage-rw compute-rw --image IMAGE

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

    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 .

Deprecating 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: 

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

The deprecation state can be any of:

Deleting an image

You can only delete images that you or someone who has access to the project has added. To delete an image using the images delete , run: 

$ gcloud compute images delete IMAGE

Building an image from scratch

Google Compute Engine is capable of running a variety of operating systems, and you can build an image from scratch with the operating system of your choice and use it on Google Compute Engine virtual machines. However, Google Compute Engine is a unique environment, with certain requirements to ensure that all images run optimally. Those requirements are described here as an advanced topic geared towards users who would like to use their own images instead of relying on public images.

This information and recommendations provided here are general in nature. Depending on your operating system, the steps to build your image can differ and you should refer to your operating system's documentation for specific instructions. Building an image is an advanced task and we suggest that only users who specifically need a new image should try to build one from scratch.

Basic operating system configuration

This section describes how to configure a very basic image that can boot within an instance. These are general recommendations and can differ depending on your operating system. Refer to the operating system's documentation for specific instructions.

Recommended

Optional

Kernel configurations

You can choose to build and run arbitrary OS kernels on Google Compute Engine if they are compliant with the hardware manifest described below. The following guidelines will help you build your own kernel binaries.

Hardware Manifest

The following is a list of devices that your kernel must support:

Required Linux Kernel Options 

# to enable paravirtualization functionality.
CONFIG_KVM_GUEST=y

# to enable the paravirtualized clock.
CONFIG_KVM_CLOCK=y

# to enable paravirtualized PCI devices.
CONFIG_VIRTIO_PCI=y

# to enable access to paravirtualized disks.
CONFIG_SCSI_VIRTIO=y

# to enable access to the networking.
CONFIG_VIRTIO_NET=y

Network configuration

In order to ensure high performance network capability, you should use the following, recommended configurations. For more information about Google Compute Engine networks, read the Networking and Firewalls documentation.

Strongly recommended

Recommended

Optional

Installing packages

Google Compute Engine requires a small set of packages to be installed to make sure that the operating systems runs smoothly.

Required packages

Strongly recommended

When setting up your packages, make sure to:

Optional

Google Compute Engine image packages

Google provides a suite of tools that configure the operating system to work properly with Google Compute Engine. The source code for these tools is hosted on GitHub. For every release , A tarball archive is provied for each tool, as well as a tarball for the whole repository. Each of the tools is described below:

For information about each package, review the respective README.md files.

Note that some of these scripts might require customization to work with your distribution. If you need to make changes, you can fork the GitHub project and save your changes in your version of the project. This forking allows your customizations to be separate from the canonical scripts and the convenience of merging in future improvements. Patches are welcome but require a third-party contributor agreement to be signed.

SSH configurations

Because you typically log in to instances via SSH, you should run your images with a secure SSH configuration.

Recommended

Next, create a sshd stub file /etc/ssh/sshd_not_to_be_run with just the contents “GOOGLE\n” . Google daemon will generate ssh keys based on the ssh metadata .

Remove ssh host keys

Don't use ssh host keys with your instance. Remove them as follows: 

rm /etc/ssh/ssh_host_key
rm /etc/ssh/ssh_host_rsa_key*
rm /etc/ssh/ssh_host_dsa_key*
rm /etc/ssh/ssh_host_ecdsa_key*

As an example, the following SSH configuration files provide a good starting point for defining your own configuration files. For your /etc/ssh/ssh_config file, start with the following configurations: 

Host *
Protocol 2
ForwardAgent no
ForwardX11 no
HostbasedAuthentication no
StrictHostKeyChecking no
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,arcfour256,arcfour128,aes128-cbc,3des-cbc
Tunnel no

# Google Compute Engine times out connections after 10 minutes of inactivity.
# Keep alive ssh connections by sending a packet every 7 minutes.
ServerAliveInterval 420

For your /etc/ssh/sshd_config file, start with the following configurations: 

# Disable PasswordAuthentication as ssh keys are more secure.
PasswordAuthentication no

# Disable root login, using sudo provides better auditing.
PermitRootLogin no

PermitTunnel no
AllowTcpForwarding yes
X11Forwarding no

# Compute times out connections after 10 minutes of inactivity.  Keep alive
# ssh connections by sending a packet every 7 minutes.
ClientAliveInterval 420

# Restrict sshd to just IPv4 for now as sshd gets confused for things
# like X11 forwarding.

Security recommendations

You should always provide a secure operating system environment but it can be difficult to strike a balance between a secure and accessible environment. Many of the precautions below are not required; however you are strongly recommended to enable them. Insecure virtual machines are vulnerable to attack and can consume expensive resources.

OS security best practices

Kernel build options

The following options are security settings that Google Compute Engine recommends when building your own kernel:

Strongly recommended

It is strongly recommended that you set the following options when building your kernel.

Recommended

Kernel security settings

A great way to harden the security of the kernel is through the kernel settings file, /etc/sysctl.conf . The following settings are recommended when setting up the file:

Strongly recommended 
# enables syn flood protection
net.ipv4.tcp_syncookies = 1

# ignores source-routed packets
net.ipv4.conf.all.accept_source_route = 0

# ignores source-routed packets
net.ipv4.conf.default.accept_source_route = 0

# ignores ICMP redirects
net.ipv4.conf.all.accept_redirects = 0

# ignores ICMP redirects
net.ipv4.conf.default.accept_redirects = 0

# ignores ICMP redirects from non-GW hosts
net.ipv4.conf.all.secure_redirects = 1

# ignores ICMP redirects from non-GW hosts
net.ipv4.conf.default.secure_redirects = 1

# don't allow traffic between networks or act as a router
net.ipv4.ip_forward = 0

# don't allow traffic between networks or act as a router
net.ipv4.conf.all.send_redirects = 0

# don't allow traffic between networks or act as a router
net.ipv4.conf.default.send_redirects = 0

# reverse path filtering - IP spoofing protection
net.ipv4.conf.all.rp_filter = 1

# reverse path filtering - IP spoofing protection
net.ipv4.conf.default.rp_filter = 1

# reverse path filtering - IP spoofing protection
net.ipv4.conf.default.rp_filter = 1

# ignores ICMP broadcasts to avoid participating in Smurf attacks
net.ipv4.icmp_echo_ignore_broadcasts = 1

# ignores bad ICMP errors
net.ipv4.icmp_ignore_bogus_error_responses = 1

# logs spoofed, source-routed, and redirect packets
net.ipv4.conf.all.log_martians = 1

# log spoofed, source-routed, and redirect packets
net.ipv4.conf.default.log_martians = 1

# implements RFC 1337 fix
net.ipv4.tcp_rfc1337 = 1

# randomizes addresses of mmap base, heap, stack and VDSO page
kernel.randomize_va_space = 2
Recommended 
# provides protection from ToCToU races
fs.protected_hardlinks=1

# provides protection from ToCToU races
fs.protected_symlinks=1

# makes locating kernel addresses more difficult
kernel.kptr_restrict=1

# set ptrace protections
kernel.yama.ptrace_scope=1

# set perf only available to root
kernel.perf_event_paranoid=2

Packaging the image

A Google Compute Engine image is a gzipped tarball that contains the raw disk file. When an image is added, Google Compute Engine validates the contents of the image to ensure it can be used. Google Compute Engine offers the gcimagebundle tool which can package your image for you. To use gcimagebundle to package your image, run: 

sudo gcimagebundle -d <boot-device> -o <output-directory>

If you would like to package the image yourself, use the following requirements for the image format.

Requirements

Your archive must satisfy these requirements before it can be added to Google Compute Engine.

Strongly recommended

The following recommendations prevent the image from using more space than necessary, which reduces the overall storage cost of the image.

See the Create a blank image file example below.

Partitions

Images can have any primary and secondary partitioning scheme that is compatible with the MS-DOS partition table. Google-supplied images typically have the following partitioning scheme:

Example: Create a blank image file

The following is an example script that describes how to create a blank image file. Note that this script is an example and your own experience can vary. 

# Create sparse blank disk file.
$ truncate disk.raw ${DISK_SIZE_MB}

# If you can’t use truncate use dd instead.
# dd if=/dev/zero of=file.img bs=1 count=0 seek=${DISK_SIZE_MB}M

# Create MS-DOS partition table.
$ parted disk.raw mklabel msdos

# Create primary partition as ext4
$ parted disk.raw mkpart primary ext4 1 ${DISK_SIZE_MB}

# Create compressed and sparse image tarball
$ tar -Szcf image.tar.gz disk.raw

Upload an image into Compute Engine

Once you have built your image tarball, you must upload your image into a Google Cloud Storage bucket before you can add the image to your Compute Engine project.

To add a custom image to your project from a tar file of an existing image, you must first add the image to Google Cloud Storage and import it to your Compute Engine project. Use the following instructions to help you add your image to Compute Engine.

  1. Upload your tar file to 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. Set up gsutil.

      If this is your first time using gsutil on this instance AND you didn't set up your instance to use a service account to talk to Google Cloud Storage, run gsutil config and follow the instructions. Otherwise, you can skip this step.

    2. Create a bucket.

      The following restrictions apply when you create a Cloud Storage bucket to store your image file:

      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 .

    3. Copy your file to your new bucket. 

      me@example-instance:~$ gsutil cp /tmp/<your-image>.image.tar.gz gs://<bucket-name>

  2. Add your customized image to the Images collection

    Log out of your instance by typing exit . Add your saved image to your project's Images list using gcloud compute on your local machine, as described below. When you add your image to the Images collection, you must choose an image name that is unique among all images in the project and specify the URI of your image in Google Cloud Storage, using the URI scheme shown below. 

    $ gcloud compute images create IMAGE-NAME --source-uri URI

    The URI to the bucket can be one of the following formats:

    You can check if the image is ready to use by performing a [ images describe ]/cloud/sdk/gcloud/reference/compute/images/describe) command, with returns the image state as well. After the image is READY , you can use it for your instances.

    Because you are charged for using the Google Cloud Storage service, you can delete your Google Cloud Storage object once you are done with it. After you delete the object, you won't be able to use it again, unless you reupload another copy.

    If you do choose to delete your Google Cloud Storage object, you must first wait until Compute Engine has finished adding the image and the new image is marked as READY in Compute Engine.

  3. Use your custom image

    Whenever you want to start a new instance with your custom image, specify the --image flag with the name that you assigned your image in the previous step: 

    $ gcloud compute instances create INSTANCE [INSTANCE ...] --image IMAGE

    If you choose to create multiple instances with one command, gcloud compute uses the same image for all of the instances and each instance will have its own unique IP address.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.