Creating and Sharing Images

Overview

Users with project administrator and collaborator roles have the capability to create images for their projects. Images may also be made available by silo administrators and collaborators to all project users.

While the Oxide Rack does not come with any preloaded machine images, many Linux distros provide native cloud images that can be deployed in the Oxide rack. Here is an example for a quick start:

  1. Download this generic cloud image from Debian: https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.raw.

  2. Navigate to the Images section of your project on the web console

  3. Click Upload Image, enter the required details, and select the Debian .raw image file

Upload Image Stages

The process involves creating a boot disk, taking a snapshot, and making an image out of it. The disk and snapshot are treated as intermediate artifacts and will be removed automatically once the image has been successfully created.

You can also import an image with the CLI which follows the same disk-snapshot-image workflow. The only difference is that the disk and snapshot are retained afterwards:

oxide disk import \
    --path /tmp/debian-12-genericcloud-amd64.raw \
    --disk debian12-boot \
    --project prom-dev \
    --description "debian 12 cloud image from distros" \
    --snapshot debian12-snapshot \
    --image debian12 \
    --image-description "debian 12 original base image" \
    --image-os debian \
    --image-version "12"

If further changes are required on the import file before turning it into a reusable image, you can invoke the CLI command without specifiying the snapshot and image parameters, and optionally, pass the disk size and block size parameters, e.g.

oxide disk import \
    --path /tmp/debian-12-genericcloud-amd64.raw \
    --disk debian12-boot \
    --disk-size 3221225472 \
    --disk-block-size 512 \
    --project prom-dev \
    --description "debian 12 cloud image from distros"

The disk created can then be used for provisioning a new instance, allowing the content to be modified in a running VM instance. When the desired changes are completed, you can stop the VM and take a snapshot of the disk to produce a reusable image for yourself and other users.

Important
The disk block size must match the one used for creating the image. If none is provided, it is set to 512 by default.

Image Attributes

Image names must meet the following requirements:

  • is unique within the project

  • start with a letter

  • contain only lower-case letters, numbers, and dashes

  • cannot be a UUID (but can contain one)

Besides name and description, Other built-in image attributes include:

  • os: the operating system family that the image runs on, e.g. Ubuntu, Debian

  • version: the operating system or application version string

  • digest: hash of the image contents, e.g.sha256

  • size: image total size in bytes

Preparing Images for Import

Linux Images from Providers

Many Linux distros have native cloud images that meet all the prerequites for running on the Oxide rack, for example,

Images built for x86_64 or amd64 architecture in RAW format can be used directly as the source of data import. For images in other formats, you can use the open source tool qemu-img to convert the root disk to RAW format, e.g.

qemu-img convert -f qcow2 -O raw jammy-server-cloudimg-amd64.img jammy-server-cloudimg-amd64.raw
qemu-img convert -f vmdk -O raw myimage.vmdk myimage.raw

Building Your Own Image

If you plan to build custom images from other sources, please ensure to include the following prerequisites for the instance to boot up and allow remote access:

  • cloud-init, and/or any other scripts for bootstrapping

  • virtio driver, if it does not come with the operating system (e.g. Windows)

  • mechanisms for setting login credentials (e.g. SSH keys, local account, password) during initialization

  • any necessary tools or settings to allow remote server management

  • any operating system licenses, if applicable

Sharing Images with Other Projects

Silo administrators can make a set of shared images for all project users with the promote image functionality. The images to be shared can be first created and tested within a project. Once the images are ready for broader access, users with the silo "admin" role can make image_promote API calls to move them out of the project. Users with the silo "viewer" role will be able to see these images in a list or view image request and use them to create disks and VMs.

Related API References

Last updated