Image families best practices

This document explains the best practices when using image families on Compute Engine.

Before you begin

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:
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Public image families

Compute Engine provides image families to help you ensure that your automation systems can reference the latest images. As an administrator, you can group a set of images as an image family. Then users of the images only have to keep track of the image-family name, rather than an exact image name. Because image names must be unique, image-build pipelines often create image names with information encoded in them, such as the application name, date, and version, for example, my-application-v3-20210101. In automation tools, you can reference the image family name instead of having to update the image name at intervals. Using image families ensures that you always access the latest image in the family, for example, my-application.

Image families.

Public images are grouped into image families. A public image family always points to the latest version of an image that is available in each zone. When new images are released globally, their initial availability in image families is zone dependent, which improves zonal fault tolerance for your workflows during Google image updates.

During image rollout, the latest version of an image in an image family might differ in different zones. For example, the debian-10 image family in the debian-cloud project always points to the most recent Debian 10 image, but the most recent Debian 10 image in zone us-central1-a and southamerica-east1-b might be different.

When you create VMs from image families using the Google Cloud CLI, Compute Engine uses the latest image that is available in your VM's zone for your request. When you create VMs using the Google Cloud console, Compute Engine only displays the public images available in your selected zone. If you want to create VMs using the latest globally available image, use the gcloud CLI instances create command and specify --image-family-scope=global.

Viewing the latest available image version

You can view the latest globally available image in an image family, or view the latest image that is available in a particular zone.

Globally

To view the latest globally available image in an image family, use one of the following methods:

gcloud

Use the gcloud compute images describe-from-family command:

gcloud compute images describe-from-family IMAGE_FAMILY_NAME  \
   --project=IMAGE_PROJECT

Replace the following:

IMAGE_FAMILY_NAME: the name of the image family that you want to search. For a full list of image family names, see Operating system details.
IMAGE_PROJECT: the name of the image project. For a full list of image project names, see Operating system details.

REST

Make a GET request to the images.getFromFamily method:

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

Replace the following:

IMAGE_PROJECT: the name of the image project. For a full list of image project names, see Operating system details.
IMAGE_FAMILY_NAME: the name of the image family that you want to search. For a full list of image family names, see Operating system details.

Per zone

To view the latest available image in an image family for a specific zone, use one of the following methods:

gcloud

Use the gcloud compute images describe-from-family command with the --zone flag:

gcloud compute images describe-from-family IMAGE_FAMILY_NAME  \
   --project=IMAGE_PROJECT \
   --zone=ZONE

Replace the following:

IMAGE_FAMILY_NAME: the name of the image family that you want to search. For a full list of image family names, see Operating system details.
IMAGE_PROJECT: the name of the image project. For a full list of image project names, see Operating system details.
ZONE: the zone you want to query.

REST

Make a GET request to the imageFamilyViews method:

GET https://compute.googleapis.com/compute/v1/projects/IMAGE_PROJECT/zones/ZONE/imageFamilyViews/IMAGE_FAMILY_NAME

Replace the following:

IMAGE_PROJECT: the name of the image project. For a full list of image project names, see Operating system details.
ZONE: the zone you want to query.
IMAGE_FAMILY_NAME: the name of the image family that you want to search. For a full list of image family names, see Operating system details.

Custom image families

You can create custom image families for your custom images. The image family points to the most recent image that you used to create the image family. To roll an image family back to a previous image version, you can deprecate the most recent image in that family (as long as the previous image is not deprecated). For more information, see Setting image versions in an image family.

To create an image with an image family, or to create an image family if one doesn't exist, you must add an additional --family flag to the image create step, for example:

gcloud compute images create my-application-v3-20210101 \
    --source-disk my-application-disk-1 \
    --source-disk-zone us-central1-f \
    --family my-application

After you run this command, any calls to run an instance based on the image my-application points to the newly created image, my-application-v3-20210101.

When selecting a name for your image family, review Naming convention.

How to use image families

While image families let you reference the latest image, the latest image might introduce incompatibility with your application, which can cause issues in a production environment if it is not validated. If you want to leverage the benefits of image families while reducing the risks, we recommend that you test the latest referenced image from the image family before using it in your production environment.

In summary, you can consider the following approach:

Set up a testing environment separate from your production environment.
In the testing environment, complete the following steps:
- Create a custom image family from the source image family.
- Verify the stability of the new image in the custom image family against your workloads.
Once verified, move this custom image family to a production environment.

For example, the process might resemble the following procedure.

In your test project, create an image from the source image family. This new image source family must also have its own custom image family to reference in the test environment. To create the image with a custom image family, run the following command:
```
gcloud compute images create test-image-name \
--source-image-project source-project \
--source-image-family source-image-family \
--project test-project \
--family test-image-family
```
Replace the following:
- test-image-name: name of your test image.
- source-project: project that the source image family belongs to.
- source-image-family: name of the source image family.
- test-project: name of the test project that you want to add the image family to.
- test-image-family: name of your test image family.
Using your custom image family test-image-family, create a VM to test your workload. To create the VM, run the following command:
```
gcloud compute instances create test-instance-name \
--image-family your-test-image-family \
--project test-project
```
Replace the following:
- test-instance-name: name of your test instance.
- test-image-family: name of your test image family.
- test-project: name of your test project.
When you have validated that this image works well for your workload, copy the image to your production environment.
```
gcloud compute images create prod-image-name \
--source-image-family test-image-family \
--source-image-project test-project \
--project prod-project \
--family prod-image-family
```
Replace the following:
- prod-image-name: name of your production image.
- test-image-family: name of your test image family.
- test-project: project that the test image family belongs to.
- prod-project: name of your project that is in the production environment.
- prod-image-family: name of the image family that you want to use in your production environment.