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
The launchInstance mutation accepts imageFamily in place of imageUrn. Set exactly one of the two. The origin compute launch-instance command has no family option and takes --image-urn only. To find a family’s current image for the CLI, query images through the API and pick the platform-provided image whose family matches and whose isFamilyCurrent is true, then launch by its URN.
You can make the same pick from the output of origin compute list-images, which includes family and isFamilyCurrent for platform-provided images. For example, with jq:
origin compute list-images --project-urn <project-urn> \
| jq -r '.. | objects
| select(.family? == "<family-slug>" and .isFamilyCurrent? == true)
| .urn'Pass the printed URN to launch-instance as --image-urn. The CLI help for list-image-families mentions an --image-family option, but launch-instance doesn’t accept one.
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 '<slug>' 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.