Upload OS images
An OS image that names an OS image store holds its own file. You upload the file once, and node providers download it from the platform when they provision a machine.
The file never passes through the platform. Uploads use the S3 multipart upload, which AWS introduced for S3 and which is now the common way to move large files into object storage. The file is split into parts that can be sent in parallel and retried one at a time, so a failed part doesn't restart the whole upload. The platform signs a URL for each part, and the client sends each part straight to the bucket. After the last part, the client asks the platform to assemble the file.
Prerequisites​
- An OS image store connector whose
StoreAccessiblecondition isTrue. - A license that includes machine management. Creating an image that names an image store, uploading, and finalizing require it.
- Permission to update the
OSImage. Uploading counts as an update, sospec.ownerandspec.accessdecide who may upload. - For users who aren't admins, a role that allows
createon theosimages/uploadandosimages/finalizesubresources. - For tenant users, an image the tenant owns. A tenant can't upload to an image a platform admin owns, even one granted to the tenant. To create its own images, the tenant's
osImagescapability must allow custom images, and the tenant must be granted the image store connector through itsconnectorscapability. See What each capability offers. Images a tenant creates are named<tenant>--<name>. The platform UI adds the prefix for you. - A file in
qcow2format. Images can be up to 1,250 GiB.
Create an OSImage​
The CLI and the API upload to an OSImage that already exists, so create it with kubectl first. To create the image and upload the file in one step, skip to Upload in the platform UI.
For the kubectl commands on this page, connect to the platform management API.
apiVersion: management.loft.sh/v1
kind: OSImage
metadata:
name: ubuntu-noble
spec:
displayName: Ubuntu Noble (24.04 LTS)
# Name of the OS image store connector that holds the file.
connectorRef: os-images
# qcow2 is the only supported format.
format: qcow2
kubectl create -f ubuntu-noble.yaml
| Field | Description |
|---|---|
spec.connectorRef | Name of the OS image store connector. The platform rejects a name that isn't an OS image store connector. You can't change it after you set it. |
spec.format | Format of the file. Must be qcow2 before you upload. You can't change it after you set it. |
spec.properties | Optional provider properties, such as kubevirt.vcluster.com/root-disk-size. |
The uploaded file is the image source, so the platform rejects an image that also sets a provider's own source, such as metal3.vcluster.com/image-url, metal3.vcluster.com/image-checksum, kubevirt.vcluster.com/image-url, or kubevirt.vcluster.com/image-datasource. Provider properties that don't name a source still apply.
The Metal3, KubeVirt, and NICO node providers use the uploaded file. Set the properties the provider needs besides the source. In the platform UI, set them in the Image Properties section. For KubeVirt, add kubevirt.vcluster.com/root-disk-size, and machines.vcluster.com/os-image-type: kubevirt to show the image in KubeVirt image selection. See Provider-specific properties.
A new image starts in the Pending phase. If no upload starts within 24 hours, the image moves to Failed. You can still upload to it afterwards.
Upload in the platform UI​
The platform UI creates the image and uploads the file in one step. Browser uploads need a CORS rule on the bucket.
- In the sidebar, click Operating System. Click Images if it's shown, then click .
- Enter a name for the image.
- In the OS Image section, set Image source to File Upload.
- In Bucket, choose the OS image store connector. You can't change it later.
- Drop the
qcow2file into the upload field. - Click . Keep the page open until the upload finishes.
The image's status in the list moves from Uploading through Verifying to Ready. Tenant users see Image Pending until the image is Ready or Failed.
If no image store is available, the Bucket field and the upload field are disabled. A platform admin sees No image store connected and a action. A tenant user sees File upload is not available and needs a platform admin to grant the tenant an image store connector.
To upload a file to an image that already exists, open the image, drop the file, and click .
Resume a browser upload​
The browser sends four parts at a time and retries parts that fail on a temporary error. If the upload still fails, the status shows Upload failed with the reason. Click to continue. Parts that already landed aren't sent again, as long as the panel stays open with the same file selected.
Keep the page open while the upload runs. While a file uploads, is disabled and you can't close the panel. Only reloading or leaving the page stops the browser upload, and the browser asks you to confirm first.
Stopping the browser upload preserves the image. Its upload session stays valid until the image's deadline. To continue, open the image and select the same file. The panel shows the size and deadline of the unfinished upload. The browser remembers landed parts only while the panel stays open, so reopening it sends every part again. A file of a different size is refused while the session is open.
If an upload fails after creating a new image, closing the panel asks whether to keep or delete the image. Click to upload the file later, or to remove it.
leaves the image as it is. It stays Pending or Uploading until its 24-hour deadline, then moves to Failed with the reason Expired. A Failed image still accepts a new upload, so you can upload the file after the deadline too. is the same as deleting the image from the list. The platform cancels the open upload, removes any incomplete data from the image store, and then removes the image. See Retry and replace an image.
Upload with the CLI​
Log in to the platform with the vCluster CLI, then upload to an existing image:
vcluster platform upload osimage "ubuntu-noble" --file "noble-server-cloudimg-amd64.img"
The command waits until the image is Ready. Pass --skip-wait to return as soon as the upload is finalized.
The CLI doesn't create images. If the image doesn't exist, create it first as shown in Create an OSImage.
Upload with the API​
Use the API to upload from your own tooling. The flow has four steps:
- Request upload targets with
upload, one batch of up to 10 parts at a time. PUTeach part to its target URL.- Complete the upload with
finalizeand the file's sha256 checksum. - Wait until the image phase is
Ready.
Both endpoints are subresources of the OSImage in the management.loft.sh/v1 API group. Authenticate with a platform access key:
export PLATFORM_HOST="platform.example.com"
export ACCESS_KEY="<access-key>"
export IMAGE="ubuntu-noble"
export FILE="noble-server-cloudimg-amd64.img"
export API="https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/osimages/$IMAGE"
Request upload targets​
Send the size of the file in bytes. The first call opens the upload session:
SIZE=$(wc -c < "$FILE" | tr -d ' ')
curl -s -X POST "$API/upload" \
-H "Authorization: Bearer $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d "{\"apiVersion\":\"management.loft.sh/v1\",\"kind\":\"OSImageUpload\",\"spec\":{\"sizeBytes\":$SIZE}}" \
> batch.json
The response is an OSImageUpload with one batch of targets. This example omits targets 3 through 10:
{
"kind": "OSImageUpload",
"apiVersion": "management.loft.sh/v1",
"spec": {
"sizeBytes": 2071724032
},
"status": {
"partSizeBytes": 134217728,
"totalParts": 16,
"nextPart": 11,
"targets": [
{ "partNumber": 1, "url": "https://my-os-images.s3.eu-central-1.amazonaws.com/..." },
{ "partNumber": 2, "url": "https://my-os-images.s3.eu-central-1.amazonaws.com/..." }
],
"expiresAt": "2026-10-15T10:00:00Z"
}
}
| Field | Description |
|---|---|
spec.sizeBytes | Size of the whole file in bytes. Every call of the same session must send the same value. |
spec.fromPart | Optional. Part number the batch starts at. Defaults to 1. |
status.partSizeBytes | Size of every part except the last, currently 128 MiB. Read it from the response instead of hard-coding it. |
status.totalParts | Number of parts the file is split into. |
status.targets | Up to 10 targets, each with a partNumber and a url. |
status.nextPart | Value to send as spec.fromPart for the next batch. Absent on the last batch. |
status.expiresAt | Time when the target URLs in this batch stop working, 24 hours after the call. |
Upload the parts​
Part numbers start at 1. Part n covers the partSizeBytes bytes that start at offset (n - 1) * partSizeBytes. The last part holds the remaining bytes.
Send each part with a plain PUT to its target URL. The URL already carries its authorization, so don't add any headers. The request must state a Content-Length. The store rejects chunked uploads.
PART_SIZE=$(jq -r '.status.partSizeBytes' batch.json)
jq -r '.status.targets[] | "\(.partNumber) \(.url)"' batch.json |
while read -r PART URL; do
dd if="$FILE" of=part.bin bs="$PART_SIZE" skip=$((PART - 1)) count=1 2>/dev/null
curl -sf -X PUT --upload-file part.bin "$URL" || echo "part $PART failed"
done
A failed part can be sent again. Uploading the same part number again replaces it.
The client must reach the store at the address in the URL. The signature covers the host name, so a proxy or port-forward has to keep the original Host header.
Request the next batch​
While the response has a nextPart, call upload again with the same sizeBytes and nextPart as fromPart, then upload that batch:
NEXT=$(jq -r '.status.nextPart // empty' batch.json)
curl -s -X POST "$API/upload" \
-H "Authorization: Bearer $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d "{\"apiVersion\":\"management.loft.sh/v1\",\"kind\":\"OSImageUpload\",\"spec\":{\"sizeBytes\":$SIZE,\"fromPart\":$NEXT}}" \
> batch.json
Repeat until a response has no nextPart. Later calls reuse the open session, so you can request batches ahead of the parts you're still uploading.
To refresh targets that are about to expire, call upload again with fromPart set to the first part that hasn't landed yet. Each call also extends the image's 24-hour deadline.
Finalize the upload​
When every part has landed, send the sha256 checksum of the whole file as 64 lowercase hex characters:
# On Linux, use sha256sum instead of shasum -a 256.
CHECKSUM=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)
curl -s -X POST "$API/finalize" \
-H "Authorization: Bearer $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d "{\"apiVersion\":\"management.loft.sh/v1\",\"kind\":\"OSImageFinalize\",\"spec\":{\"checksum\":\"$CHECKSUM\"}}"
The platform checks that every part arrived, assembles the file in the image store, and answers with status.completedAt. If parts are missing, it answers 409 and names how many parts landed. Upload the missing ones and call finalize again.
The platform records the checksum and hands it to node providers, which verify the file when they download it. The platform doesn't verify the checksum itself, so compute it from the same file you uploaded.
Calling finalize again with the same checksum is safe and returns the original completedAt. Retry it when a connection drops.
Wait until the image is ready​
finalize doesn't make the image Ready. The platform first checks that the assembled file has the size you declared. Watch the phase:
kubectl get osimage ubuntu-noble -w -o custom-columns=NAME:.metadata.name,PHASE:.status.phase
Node providers can use the image once the phase is Ready. A machine that references an image that isn't Ready yet waits for it. A machine that references a Failed image fails to provision.
Network access for provisioning​
A node provider downloads an uploaded image from https://<platform-host>/osimages/blob/<uid>, where <uid> is the image's metadata.uid. The platform answers with a redirect to a download URL signed for one hour, so the file comes straight from the image store.
Whatever downloads the image for the node provider must reach both addresses:
- The platform's public host name.
- The bucket endpoint that the image store connector names.
The blob address needs no credentials, because a node provider holds none. The random uid is the only authorization, and anyone who has the address can download the image while it exists. The uid is hard to guess, but the endpoint doesn't stop repeated attempts to guess it. Treat the address as a secret.
Don't build credentials, private keys, or other secrets into an OS image. If an address leaks or is guessed, the image holds nothing an attacker can reuse.
While the image is still uploading, the address answers 409 with Retry-After: 30. For a Failed image, it answers 409 without Retry-After, and for an unknown uid it answers 404.
Image status​
| Phase | Meaning |
|---|---|
Pending | The image exists and no upload has started. |
Uploading | An upload session is open. |
Ready | The file is assembled and has the declared size. |
Failed | The upload didn't finish. The Uploaded condition names the reason. |
The status carries these fields:
| Field | Description |
|---|---|
status.expiresAt | Deadline of a Pending or Uploading image: 24 hours after the last upload call, or after creation if no upload has started. |
status.store.location | Object key of the file in the bucket. |
status.store.sizeBytes | Size of the file as the store reports it. |
status.store.checksum | sha256 checksum sent with finalize. |
status.conditions | The Uploaded condition, with the reason for a Failed phase. While the store refuses an upload or finalize call, also the StoreAccessible condition. Its reason and message name the setting to fix, using the same reasons as the connector check. The condition is removed when a later call succeeds or the image becomes Ready or Failed. |
The Uploaded condition reports one of these reasons when the upload fails:
| Reason | Cause |
|---|---|
Expired | The deadline passed before the upload was finalized. |
SizeMismatch | The assembled file doesn't have the size sent as sizeBytes. |
ObjectMissing | The upload was finalized but the store doesn't hold the file. |
InvalidSession | The platform can't read the recorded size of the upload session. Start the upload again. |
Retry and replace an image​
A Failed image accepts a new upload. Run the CLI again, or start the API flow again from the first upload call. The image keeps its name, owner, and access rules, and node providers that already reference it keep working.
An image that is Ready refuses another upload with 409 Conflict. To use a different file, delete the image and create it again.
Deleting an image removes its file from the image store and aborts an open upload. The image stays in Deleting until the store confirms the file is gone. Delete the images in an image store before you disconnect its connector.
The platform can't fully remove an image while its store is unavailable, for example because its credentials changed or its connector was deleted. The image waits in Deleting until the store answers again. If the store won't come back, see Finish a stuck delete.
To upload a file of a different size while a session is open, delete the image and create it again. A session only accepts the size it was opened for.
Troubleshoot uploads and deletes​
Fix upload errors​
| Response | Cause and fix |
|---|---|
409 with the upload is already complete | The image already holds a file. Delete the image and create it again to upload a different file. |
409 with upload session was opened for <n> bytes | sizeBytes doesn't match the size of the open session. Send the original size, or delete and recreate the image. |
409 with <n> of <m> parts have been uploaded | finalize found missing parts. Upload them and call finalize again. |
409 with the upload was completed with checksum | finalize was called again with a different checksum than the first call. |
409 with no open upload session to finalize | No upload was started, or the session failed. Start again with upload. |
409 with the upload session is gone and no object was assembled | The store no longer holds the session or a finished file. Delete the image and create it again. |
422 on spec.connectorRef | The image names no image store, or the connector can't be used. Check the connector name and its StoreAccessible condition. |
422 on spec.format | The image format isn't qcow2. |
422 on spec.sizeBytes or spec.fromPart | The size is 0 or larger than 1,250 GiB, or fromPart is outside 1 to totalParts. |
422 on spec.checksum | The checksum is missing, isn't 64 characters, or isn't lowercase hex. Send the sha256 of the file as lowercase hex. |
400 naming the image store connector | The store refused the request. The message names the setting to fix. See Check the connection. |
400 with dry-run is not supported | upload and finalize change the image store, so they don't accept a dry run. Send the request without --dry-run or dryRun. |
500 Internal Server Error and a StoreAccessible reason of Unreachable | The store didn't answer. Check the connector's endpoint and that the store is running. |
403 Forbidden | You can't update the image, or the license doesn't include machine management. |
403 from the store on a PUT | The target expired, the request added an x-amz-* header, or the host differs from the signed URL. Request the target again with fromPart. |
| CORS error in the browser | The bucket has no CORS rule for the platform address. See Allow browser uploads. |
Finish a stuck delete​
An image stays in Deleting while its store can't be reached. Fix the connector's credentials or endpoint, and the delete finishes when the store answers again.
If the store is gone for good, remove the platform.vcluster.com/cleanup-os-image-blob finalizer from the image to finish the delete. Open the image for editing and delete that entry from metadata.finalizers:
kubectl edit osimage ubuntu-noble
The image disappears once you save. The file stays in the image store, and the platform never removes it later.