Labels
In Stretchy, labels control almost everything: the operating system image to start, the amount of hardware resources (CPU, memory, …) to assign to a virtual machine, and on which computer the virtual machine should be placed.
Labels in a Nutshell
Labels are alphanumeric strings (ASCII) that may contain dashes, underscores, dots, and spaces. Valid examples are Windows 11, size-m or 14862047262-1.
Apart from the restrictions we mentioned, you are free to choose the labels of your liking.
| Labels are case-sensitive. |
Object Selection
Stretchy Orchestrator selects an object (operating system image, flavour, …) by comparing the labels attached to a job with the labels assigned to the respective object. Of each object type (operating system, flavour, …), it picks the one with the highest number of matching labels.
Unknown labels are ignored.
Expecting a combination of two or more labels (such as arm32 and linux) to be present to select an object like a flavour is a recipe for nasty surprises. Stretchy Orchestrator interprets that as arm32 OR linux, meaning that only one must be present, and the other one is optional.
|
Required Labels
Some object types allow specifying a list of required labels. All required labels must be present on a job for an object to be considered. If only one required label is absent, the object is excluded from consideration.
Recommendations
Due to its powerful nature, it is very tempting to create a sophisticated labelling system only to end up with jobs on Windows that were originally destined for Alpine Linux.
Therefore, we recommend a relatively modest labelling system that should work for most users. Throughout the manual, we introduce extensions for advanced use cases.
| Ensure that each label uniquely identifies an object, like a flavour or a node. |
Images
It is common to create operating system images of specific versions, like Ubuntu 24.04 or Windows Server 2025. We recommend assigning one label to each image that uniquely identifies such a version, for example, windows-server-2025.
If your setup supports multiple CPU architectures, the label should also include the CPU architecture, for example, ubuntu-2404-amd64 and ubuntu-2404-riscv64, because images are usually bound to a specific CPU.
| When using hardware emulation, use the CPU architecture of the guest, not the host. |
Nodes
Not all nodes might be able to run all images or have the space to hold them all. The most foolproof approach is therefore to attach the label of each image installed on the node to it.
ubuntu-2404-amd64 and windows-server-2025-amd64 are installed on a node, attach both labels ubuntu-2404-amd64 and windows-server-2025-amd64 to the node.
| If an image has multiple labels, attach all image labels to each node that the image is installed on. Otherwise, machines with a missing label might wait forever for a node to become available. |
Flavours
Flavours determine the amount of hardware resources that are assigned to a virtual machine or container. There are two approaches that work well in practice:
-
Reusing the images' labels
-
Flavour-specific labels
Reusing the images' labels like ubuntu-2404-amd64 or windows-server-2025 is the easiest, but least flexible option. If you create a flavour with the label windows-server-2025 that assigns 8 CPU cores and 16384 MB of RAM, then every job using the image windows-server-2025 automatically gets 8 CPU cores and 16384 MB of RAM.
If that is too rigid for your use case, then you can define as many flavours as you like and assign a unique label to each. For example, you could create size-m that provides 4 CPU cores with 8192 MB of RAM and size-l that provides 8 CPU cores with 16384 MB of RAM. That allows choosing the desired amount of resources when configuring a job. For example, combining windows-server-2025 with size-m would result in a virtual machine with Windows Server 2025 that can access 4 CPU cores and 8 GB of memory, whereas selecting size-l instead would give the machine double that capacity.