cloud-image-index

A public, machine-readable directory of operating system cloud images published by their upstream vendors: which images exist, the exact current builds, and where to download and verify them.

The index is a tree of static JSON files, regenerated by scheduled GitHub Actions that query each vendor, and served from GitHub Pages. The format is defined as a Dropshot API trait. Its OpenAPI description is published with the index as v1/openapi.json, so clients can be generated for any language.

We are a directory, in the spirit of endoflife.date: we tell you what the vendor publishes and where. Images are always downloaded from the vendor, and clients decide for themselves how much to trust us versus cross-checking against the vendor.

One exception: the OpenBSD project does not publish cloud images, so the index lists a community build from https://github.com/hcartiaux/openbsd-cloud-image, as "OpenBSD (community build)". Its checksums come from the same place, so for OpenBSD "the vendor" means that project, not the OpenBSD project.

The index is published at https://cloud-images.tritoncloud.io/v1/index.json, with every current build in one file at https://cloud-images.tritoncloud.io/v1/images.json and its OpenAPI description at https://cloud-images.tritoncloud.io/v1/openapi.json, and regenerated daily. See docs/design.md.

Stability

From 1.0:

• The index format is the three published files under v1/: index.json, images.json and openapi.json. Within v1/, changes are compatible ones only: new optional fields, and new values for the fields whose description says the set can grow (aliases, image formats, compressions, firmware, location kinds, digest algorithms, checksum formats, signature kinds). Clients must ignore fields they do not know and accept those new values. A breaking change goes to a new v2/ tree, published alongside v1/. Other files in the tree (per-distro files, the landing page) are not part of the format and may change at any time. Release ids follow the vendor's naming and can change with it; the aliases name the current release of each kind: latest the newest generally available, lts the newest long-term support, and dev the development release.
• cloud-image keeps its commands, options, avail columns and -j fields, exit codes and install locations through 1.x. New ones may be added; removing or changing one waits for 2.0.

Report security issues privately, as SECURITY.md describes.

cloud-image for SmartOS

cloud-image lists the images in the index and imports them into a SmartOS host with imgadm, checking each download against both the index and the vendor's own checksum file. Install or update it in the global zone with:

curl -fsSL https://github.com/TritonDataCenter/cloud-image-index/releases/latest/download/install.sh | bash

This installs /opt/tools/sbin/cloud-image and its man page, cloud-image(8). Then cloud-image avail lists the images and cloud-image import imports one, named by a UUID or NAME from that list (cloud-image import ubuntu-resolute-nocloud) or by distro and release or alias (cloud-image import ubuntu latest). Later, cloud-image self-update updates both to the newest release. The man page also explains how to boot the images with vmadm and pass them cloud-init user-data.

To release a new version, bump version in tools/cloud-image/Cargo.toml, merge that, and push a matching tag from the merge commit:

git tag -m "cloud-image v1.0.1" v1.0.1
git push origin v1.0.1

The illumos workflow builds the binary and publishes it, with SHA256SUMS and install.sh, as a GitHub release, but only if the tagged commit is on main, passes ci.yml's checks, and the tag matches the crate's version.