OS Images

Modify the following with your specific values to replace on the whole page and generate copyable commands:

IMAGE_URL

IMAGE_CHECKSUM

CHECKSUM_TYPE

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.

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.

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