The Cluster Image Library
A cluster keeps one library of images. An image is added to it once, under one name and one id, and each member that needs it keeps its own copy. A machine can then be created on any member that holds a copy of the image it starts from.
This page covers the library: adding an image to it, copying an image to another member, removing a copy, removing an image, and publishing an image that a member already has. The rules for images on a single node are on Images.
Part of Clustering. The library needs every member
to run a version that supports it. Below that, the
library's routes answer that every member must run a version that supports this.
Reads are never refused by the licence; changes need compute in the licence of
the member that makes them.
What the library holds
Each library entry has:
- a name, unique across the whole cluster;
- an id, the same on every member, so a machine refers to its image the same way everywhere;
- the image's SHA-256 and size, which every copy is checked against;
- its kind: a base image, or a template made from a machine;
- the tenant it belongs to, or none for an image the operator added, and whether a template is shared with every tenant;
- the members that hold a copy.
What the cluster shares is the entry. The bytes stay on each member that holds a copy. The checksum and the size of an image cannot change once it is in the library: an image that arrives under an id already in use, with a different checksum or size, is refused with **"This image is already in the cluster with a different checksum or size."**
A name is unique across the cluster. A second image with the same name is refused with "Another image in the cluster already has this name."
Adding an image to the library
Add an image from an address, with its SHA-256, or from the node's catalogue:
sudo cenvero-str-ctl --node edge-1 cluster image add --name debian-13 \
--url https://images.example.net/debian-13-genericcloud-amd64.qcow2 \
--sha256 <64 hexadecimal characters>
sudo cenvero-str-ctl --node edge-1 cluster image add --name almalinux-9 --catalogue almalinux-9-genericcloud
The member named with --node (this node, when none is named) brings the image
in. The answer is at once: the new image's id and the task that downloads it.
The download is checked against the SHA-256, and the image joins the library once
it is ready on that member, with that member as its first holder.
Give exactly one source: a catalogue entry, or an address with its SHA-256. Anything else is refused with 400 and the message "give exactly one source: a catalogue entry, or a URL with its sha256".
Over the API, POST /api/v1/cluster/images takes {"name", "node", "url", "sha256"}
or {"name", "node", "catalogue"} and answers 202 with the id and the task. A
name another image holds is 409.
Copying an image to another member
A create never fetches an image. A machine is created on a member that already holds its image. On a member without the image, the create is refused with "The image is not on this member. Copy it to this member first." The placement answer lists the image's holders, so a machine placed for an image goes to a member that has it (see Placing machines).
To copy an image to a member, use the console's Copy to button in Datacenter › Images, or:
sudo cenvero-str-ctl --node edge-2 cluster image replicate <image-id>
Over the API: POST /api/v1/cluster/images/{id}/placements with {"node": "<member>"}
answers 202 with a task (image.replicate).
The copy is taken from a member that holds a verified copy, over the cluster's own connection. The member reserves the space for the whole image before the first byte arrives, so a copy that does not fit fails before it starts. The bytes are written to a partial file, and their length and SHA-256 are checked against the library's record before the file takes its name. A copy that does not match is discarded: **"The copy from the other member does not match the cluster's record of the image, so it was discarded." A copy the member already has is refused with "This member already has a copy of the image."**, and a second copy of an image started while one is running on the same member is refused with **"This image is already being copied to this member."**
Each copy appears in the library's answer as a holder in the placements list,
with the state verified.
Removing a copy from a member
sudo cenvero-str-ctl --node edge-2 cluster image evict <image-id> edge-2
The command acts on the member it names, so it is run on that member: name that
member with --node, and again as the second word. Over the API,
DELETE /api/v1/cluster/images/{id}/placements/{node} answers 200.
The console's Remove this copy does the same. Two things refuse it:
- A machine on that member uses the image. The answer is 409 and names the machines: "A machine on that member uses this image, so its copy stays. Remove or move those machines first."
- It is the only copy in the cluster. The answer is 409: "This is the only copy of the image in the cluster. Copy it to another member first."
A copy the library lists is removed this way only. The member's own
cenvero-str-ctl image delete, or DELETE /api/v1/images/{id}, is refused with
409 while the library lists that member as holding the image: **"This copy belongs
to the cluster's image library. Remove it from this member through the library instead,
which keeps the last copy in the cluster."** When a member that the library lists cannot
serve its copy, a member copying the image takes it from the next member that holds one.
Removing an image from the cluster
sudo cenvero-str-ctl cluster image delete <image-id>
Over the API: DELETE /api/v1/cluster/images/{id} answers 200. It is refused with
409 while any machine in the cluster uses the image, and names those machines:
**"Machines use this image, so it cannot be removed from the cluster. Remove those
machines first."**
Removing an image from the library does not delete the copies. Each member that held one keeps it as an ordinary image of that member, which it can use or delete like any other image on the node.
Publishing an image a member already has
An image that a member already has, and added on that member alone, joins the library with its id kept:
sudo cenvero-str-ctl image publish <image-id>
Over the API: POST /api/v1/images/{id}/publish answers 200 with the library
entry. Only an image that is ready, and whose checksum was verified, can be
published. Otherwise the answer is **"Only an image whose checksum has been verified
can be added to the cluster." or, while the image is still being prepared, "The
image is not ready on this member yet. Wait until it is ready, then try again."** A
name that another image in the cluster holds is refused as above. The member that
publishes becomes the image's first holder.
Templates and tenants
A base image can be used by a machine of any tenant. A template is made from a machine that belongs to a tenant, and only that tenant's machines can use it, unless it is shared with every tenant. The create refuses another tenant's template with the message the single node gives for it.
Who can do what
| Action | Privilege | Licence |
|---|---|---|
| Read the library, its copies and its users | Image.Audit | none (reads are never refused) |
| Add, copy, remove a copy, remove, publish | Image.Allocate | compute |
A tenant's key cannot use these routes; they answer 403.
See also
- Placing machines — how a machine finds a member that holds its image.
- Images — images on a single node, the catalogue and discs.
- Clustering Overview — what a cluster shares, and what stays with a node.
- CLI Reference — the
cluster imageandimage publishcommands. - API Reference — the image routes and their answers.