An image family is a stable name for a line of platform-provided images, such as ubuntu-22-04-minimal. A launch that names a family gets whichever image the platform has designated as current for it. A launch that names an image URN gets exactly that image until you change it.
Launch by family to pick up rebuilt images automatically. Launch by image URN to pin the image you tested against.
Launching by family
Launch with the family’s slug in place of an image: --image-family <slug> on origin compute launch-instance, or imageFamily on the launchInstance mutation. Give exactly one of the family and the image URN. To see which image a family currently resolves to, origin compute list-images shows each platform-provided image’s family and whether it is the family’s current image (isFamilyCurrent).
A family resolves separately per CPU architecture. With X86_64 as the only architecture, a family resolves to one image.
A new image is published into a family first and designated current afterward, so a family can briefly have a newer image that isn’t current yet. A family that has no current image refuses launches with “no image is currently published for this family”.
Family metadata
Read the families with the imageFamilies query or origin compute list-image-families. No permission is needed.
| Field | Meaning |
|---|---|
slug | The name to pass as imageFamily, for example ubuntu-22-04-minimal. |
vendor | Who publishes the upstream release, for example Canonical. |
os | The operating system the family tracks, for example ubuntu. |
osVersion | The release, for example 22.04. |
description | A human-readable description. |
supportEndsAt | When the upstream vendor stops supporting this release, if a date is known. |
supportEndsAt is advisory. No launch is refused on it, and running instances aren’t affected. Treat it as notice to move to a newer family.
Stable names and withdrawn families
A family is never renamed, and a name is never reused for a different line. A name in your scripts keeps meaning what it meant.
A family can be withdrawn when a newer line supersedes it. A withdrawn family:
- Drops out of
imageFamiliesandlist-image-families. - Refuses launches by its name, with “image family '
' is retired and launches nothing”. - Doesn’t affect anything you’re already running. The images published under it stay listed and can still be launched by URN.