OS Images
An OSImage resource contains the information that a node provider needs to install an operating system on a Machine, stored as a reusable reference. Instead of specifying image URLs and checksums directly on every node type or Machine, you define them once in an OSImage and reference it by name.
Create an OSImage​
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-noble
spec:
displayName: "Ubuntu Noble (24.04 LTS)"
description: "Ubuntu Noble (24.04) server cloud image for bare metal provisioning"
properties:
metal3.vcluster.com/image-url: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
metal3.vcluster.com/image-checksum: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
metal3.vcluster.com/image-checksum-type: "sha256"
Fields​
| Field | Description |
|---|---|
spec.displayName | Human-readable name shown in the UI. |
spec.description | Optional description of the image. |
spec.properties | Key-value pairs with provider-specific image configuration. |
spec.owner | Optional user or team that owns this resource. |
spec.access | Optional access control list. |
Provider-specific properties​
OS images are a generic concept. The properties they carry depend on which node provider consumes them.
Metal3​
For the Metal3 node provider, the following properties are required:
| Property | Description |
|---|---|
metal3.vcluster.com/image-url | URL of the OS image. |
metal3.vcluster.com/image-checksum | Checksum for image verification. |
metal3.vcluster.com/image-checksum-type | Checksum algorithm: md5, sha256, or sha512. Optional — auto-detected if omitted. |
KubeVirt​
For the KubeVirt node provider, an OS image defines the source and size of a VM's root disk.
The provider adds a Containerized Data Importer (CDI) DataVolume template to the generated VM.
| Property | Description |
|---|---|
machines.vcluster.com/os-image-type | Classifies the image for provider filtering in the platform UI. Set this property to kubevirt. |
kubevirt.vcluster.com/image-url | HTTP, HTTPS, or docker:// image source. Configure either this property or kubevirt.vcluster.com/image-datasource. |
kubevirt.vcluster.com/image-checksum | Optional checksum for an HTTP or HTTPS source. CDI receives the value unchanged. Include the algorithm prefix, for example sha256:<digest>. The provider ignores this property for docker:// and CDI DataSource sources. |
kubevirt.vcluster.com/image-datasource | CDI DataSource in <name> or <namespace>/<name> format. A name without a namespace resolves in the VM namespace. |
kubevirt.vcluster.com/root-disk-size | Storage request for the root disk, expressed as a Kubernetes quantity such as 20Gi. Required for every KubeVirt image source. |
Configure one source for each image. If both image-url and image-datasource are present, the provider uses the DataSource.
It discards the URL and checksum.
Container registry image source​
Use a docker:// URL to import an image from a container registry.
A checksum doesn't apply to this source type.
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-container-disk
spec:
displayName: "Ubuntu container disk"
properties:
# Show this image for KubeVirt providers in the platform UI.
machines.vcluster.com/os-image-type: kubevirt
# Import the root disk from this container registry image.
kubevirt.vcluster.com/image-url: "docker://quay.io/containerdisks/ubuntu:22.04"
# Request this amount of storage for the root disk.
kubevirt.vcluster.com/root-disk-size: "20Gi"
The provider creates a registry-backed DataVolume template and requests the configured root disk size.
Import from a web address​
Use an HTTP or HTTPS source to let CDI import a disk image. The checksum is optional and applies only to this source type.
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-noble-http
spec:
displayName: "Ubuntu Noble from HTTP"
properties:
# Show this image for KubeVirt providers in the platform UI.
machines.vcluster.com/os-image-type: kubevirt
# Import the root disk from this web address.
kubevirt.vcluster.com/image-url: "https://example.com/images/ubuntu-noble.qcow2"
# Validate the downloaded image with its published checksum.
kubevirt.vcluster.com/image-checksum: "sha256:abc123"
# Request this amount of storage for the root disk.
kubevirt.vcluster.com/root-disk-size: "20Gi"
The provider creates an HTTP-backed DataVolume template and passes the checksum to CDI.
Replace the example checksum with the checksum published for your image.
If you omit the checksum property, CDI imports the image without checksum validation.
Use a CDI data source​
Use a CDI DataSource when the source image already exists in the KubeVirt environment.
Specify <namespace>/<name> to reference a DataSource outside the VM namespace.
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-noble-datasource
spec:
displayName: "Ubuntu Noble DataSource"
properties:
# Show this image for KubeVirt providers in the platform UI.
machines.vcluster.com/os-image-type: kubevirt
# Reference an existing CDI DataSource by namespace and name.
kubevirt.vcluster.com/image-datasource: "os-images/ubuntu-noble"
# Request this amount of storage for the root disk.
kubevirt.vcluster.com/root-disk-size: "20Gi"
The provider creates a DataVolume template whose sourceRef points to the specified CDI DataSource.
For advanced disk and DataVolume customization, see the KubeVirt image configuration properties.
Use an OSImage​
Reference an OSImage by name in node type properties or Machine properties:
properties:
vcluster.com/os-image: ubuntu-noble
The platform resolves the OSImage and applies its properties during provisioning. On node providers that don't support the property, it has no effect.
Resolve image problems​
Inspect the referenced image when a KubeVirt Machine doesn't provision:
kubectl get osimage ubuntu-noble-http -o yaml
| Problem | Resolution |
|---|---|
The provider reports failed to get OSImage | The value of vcluster.com/os-image doesn't match an existing cluster-scoped OSImage. List the images with kubectl get osimages, then correct the reference. |
| The image is missing from KubeVirt image selection in the platform UI | Check machines.vcluster.com/os-image-type. Set it to kubevirt. A missing or different value classifies the image as another provider type or as custom. |
The image defines both image-url and image-datasource | Remove the source that you don't intend to use. The provider gives image-datasource precedence and ignores image-url and image-checksum. |
Provisioning reports that kubevirt.vcluster.com/root-disk-size is required | Add the property to the OS image or another effective property source. Use a valid Kubernetes storage quantity such as 20Gi. |
| Provisioning reports an unsupported image URL scheme | Use a URL beginning with http://, https://, or docker://. |
Access control​
OSImage resources are cluster-scoped. Use the spec.owner and spec.access fields to control who can use or modify them:
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-noble
spec:
displayName: "Ubuntu Noble (24.04 LTS)"
properties:
metal3.vcluster.com/image-url: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
metal3.vcluster.com/image-checksum: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
metal3.vcluster.com/image-checksum-type: "sha256"
owner:
user: admin
access:
- users:
- "*"
verbs:
- get