Set the image version in an image family

Linux Windows

Use image families to simplify image versioning. Add an image to an image family to set it as the most recent image version. If you determine that you must roll back the image family to a previous image version, deprecate the most recent image in the family.

For best practices when working with image families, see Image families best practices.

Optionally, you can specify the image's storage location by using the Google Cloud console, the gcloud compute images create command with the --storage-location flag, or the images().insert method.

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the Google Cloud CLI.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.
Read the Images document.

Set the image version in an image family

Console

In the Google Cloud console, go to the Create an image page.

Go to Create an image
Specify the Name of your image. For example, image-v1.
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 the us multi-region, or us-central1 to store it in the us-central1 region. If you do not make a selection, Compute Engine stores the image in the multi-region closest to your image's source location.
Specify the image Family for the new image. For example, add my-image-family to organize the image as part of an image family.
Optional: specify other image properties:
- Description: a description for your custom image.
- Label: a label to group together resources.
Specify the encryption key. You can choose between a 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-managed key.
Click Create to create the image.

gcloud

gcloud compute images create image-v1 \
    --source-disk disk-1 \
    --source-disk-zone us-central1-f \
    --family my-image-family

The image family points to image-v1. Add a second image to the family:

gcloud compute images create image-v2 \
    --source-disk disk-2 \
    --source-disk-zone us-central1-f \
    --family my-image-family

API

Make a POST request to the images().insert method. Specify the image family in the request body.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images

{
  "name": "image-v2",
  "sourceDisk": "/zones/us-central1-f/disks/disk-2",
  "family":"my-image-family",

}

The image family points to image-v2 because it is the most recent image that you added to the image family.

gcloud

You can see which image a family points to by running the gcloud compute images describe-from-family command.

For example:

gcloud compute images describe-from-family my-image-family

family: my-image-family
id: '8904691942610171306'
kind: compute#image
name: image-v2
selfLink: https://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v2
sourceDisk: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v2
sourceDiskId: '1677449456001963379'
sourceType: RAW
status: READY

API

Make a GET request to the images().getFromFamily method. Specify the image family in the request body.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/family

{
  "resourceId":"my-image-family",

}

If you determine that you must roll back the image family so that it no longer points to image-v2, deprecate image-v2 and the family will again point to image-v1.

gcloud compute images deprecate image-v2 \
    --state DEPRECATED \
    --replacement image-v1

Check to make sure that the image family is pointing to image-v1.

gcloud compute images describe-from-family my-image-family

family: my-image-family
id: '2741732787056801255'
kind: compute#image
name: image-v1
selfLink: https://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v1
sourceDisk: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v1
sourceDiskId: '1677449456001963379'
sourceType: RAW
status: READY