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

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud 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.

  Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Public image families

Compute Engine provides image familiesto 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. Thenusers of the images only have to keep track of the image-family name, ratherthan an exact image name. Because image names must be unique, image-buildpipelines often create image names with information encoded in them, such as theapplication name, date, and version, for example,my-application-v3-20210101.In automation tools, you can reference the image family name instead of havingto update the image name at intervals. Using image families ensures that youalways access the latest image in the family, for example,my-application.

Public images aregrouped into image families. A public image family always points to the latestversion of an image that is available in each zone. When new images arereleased globally, their initial availability in image families is zonedependent, which improves zonal fault tolerance for your workflows duringGoogle image updates.

During image rollout, the latest version of an image in an image familymight differ in different zones. For example, thedebian-12 image family in thedebian-cloud project always points to the most recent Debian 12 image, but themost recent Debian 12 image in zoneus-central1-a andsouthamerica-east1-bmight 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 foryour request. When you create VMs using the Google Cloud console, Compute Engineonly displays the public images available in your selected zone. If you want tocreate VMs using the latest globally available image, use thegcloud CLIinstances create commandand 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 thelatest image that is available in a particular zone.

Globally

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

gcloud compute images describe-from-familyIMAGE_FAMILY_NAME  \   --project=IMAGE_PROJECT

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

Per zone

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

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

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

Custom image families

You can create custom image families for yourcustom images.The image family points to the most recent image that you used to create theimage family. To roll an image family back to a previous image version, you candeprecate the most recent image in that family, provided that the previousimage is not deprecated. For more information, seeSetting image versions in an image family.

To create an image with an image family, or to create an image family if onedoesn't exist, you must add an additional--family flag to the image createstep, 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 imagemy-application points to the newly created image,my-application-v3-20210101.

When selecting a name for your image family, reviewNaming convention.

How to use image families

While image families let you reference the latest image, the latestimage might introduce incompatibility with your application, which can causeissues in a production environment if it is not validated. If you want tomake the most of the benefits of image families while reducing the risks, thenwe recommend that you test the latest referenced image from the image familybefore 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 againstyour workloads.
• Once verified, move this custom image family to a production environment.

For example, the process might resemble the following procedure.

1. In your test project, create an image from the source image family. This newimage source family must also have its own custom image family to referencein the test environment. To create the image with a custom image family, runthe following command:

   gcloud compute images createtest-image-name \--source-image-projectsource-project \--source-image-familysource-image-family \--projecttest-project \--familytest-image-family

   Replace the following:

   • test-image-name: name of your test image.
   • source-project: project that the source imagefamily belongs to.
   • source-image-family: name of the source imagefamily.
   • test-project: name of the test project that youwant to add the image family to.
   • test-image-family: name of your test image family.

2. Using your custom image familytest-image-family, create a VM to testyour workload. To create the VM, run the following command:

   gcloud compute instances createtest-instance-name \--image-familyyour-test-image-family \--projecttest-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.

3. When you have validated that this image works well for your workload, copythe image to your production environment.

   gcloud compute images createprod-image-name \--source-image-familytest-image-family \--source-image-projecttest-project \--projectprod-project \--familyprod-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 imagefamily belongs to.
   • prod-project: name of your project that is in theproduction environment.
   • prod-image-family: name of the image familythat you want to use in your production environment.