Image families best practices

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

Before you begin

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-20161011. In automation tools, you can reference the image family name instead of having to update the image name at intervals. Using image families ensure that you always returns the latest image in the family, for example, my-application.

Image families.

A public image family always points to the latest version of an image that is not deprecated. Public images are grouped into an image family. For example, the debian-9 image family in the debian-cloud project always points to the most recent Debian 9 image.

Custom image families

You can create your own images with a custom image family. 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-20161011 \
    --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-20161011.

How to use image families

While image families let you reference the latest image, the latest image may 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.

  1. 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.
  2. 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.
  3. 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.