Disks
Disks are persistent block storage volumes that can be managed independently from VM instances. Their content is, however, accessible only when they are attached to a VM. When a VM is deleted, its disks are detached and remain intact until they are manually deleted.
Disks can be provisioned from images or snapshots made on the Oxide rack, or from external images in RAW format. Regardless of the source, boot disks must have an installed operating system. You can also create blank disks to provide additional or partitioned VM storage. In summary, the options for making a disk are:
blank: creates an empty disk formatted with the block-size specified; the available options are 512, 2048, and 4096 bytesimporting_blocks: creates an empty disk that is ready for data import from an external filesnapshot: clones from an existing snapshot in the same projectimage: clones from an existing image in the same project or a shared image in the silo
Other required attributes for disk provisioning are: name, description, and total size. Disk naming is subject to the same RFC 1035 restrictions as instance and image names. The disk size must be a multiple of its block size, with a maximum of 1023 GiB.
Disk States During Provisioning
Disk provisioning may involve multiple steps depending on the method of creation. For this reason, disks may assume different states and the actions allowed also vary based on the states they are in.
The states marked by an * are transient states. In most cases, once a disk has been successfully created, the disk status is set to detached immediately. The only exception is making a disk by importing blocks because the process involves asynchronous client interactions.
Disks created through file import must go through several state transitions as shown in the diagram above:
When the disk is first created, it is set to
import_readyto await data write requests.The client controls how to chunk up the file and when to send the data chunks.
Data writes begin when the client invokes the disk_bulk_write_import_start API call.
Once the disk is in the
importing_from_bulk_writesstate, the client can issue multiple disk_bulk_write_import API calls to send the base64-encoded data chunks along with the byte offset.When all the chunks have been imported, the client signifies the end of data import with a disk_bulk_write_import_stop API call, putting the disk back to the
import_readystate.If the data import is paused or fails for any reason, the client can resume or retry bulk writes by specifying the appropriate offset.
When disk import is completed, the client invokes the disk_finalize_import API call to put the disk in a
detachedstate. The finalize action also includes an option to create a snapshot of the disk.
Canceling a Disk Import
To abandon an in-progress disk import and delete the disk, you’ll need to get the disk into a detached state by stopping the import and then finalizing it.
The CLI command to stop import is oxide disk import stop, corresponding to the API endpoint disk_bulk_write_import_stop. The CLI command for finalize is oxide disk import finalize, corresponding to the API endpoint disk_finalize_import. Once the disk has returned to the detached state, it can be safely deleted.
Disk States after Provisioning
Newly provisioned disks are set to the detached state and can be attached to an existing VM or a new instance. Each disk may only be attached to one VM at a time.
To move a disk from one VM to another, the instances involved must both be shut down for the disk to be detached and attached.
Disks can only be deleted when they are detached. Destroyed disks are irrecoverable and are not accessible in the web console or API.
* denotes transient states
Data Encryption
Server-side encryption is enabled by default and cannot be disabled. All data is encrypted both in transit (between the sled hosting the VM and sleds storing data) and at rest (on physical disks), using a key derived from the rack secret.
Snapshots
A snapshot is a lightweight point-in-time copy of a disk that can be used to create an image. One or more snapshots can be created for an attached or detached disk. Although snapshots for the same disk are stored incrementally to reduce storage space consumption, they can be retained or removed independently.
Because snapshots are different versions of a disk, they can be used to roll back or forward a VM’s on-disk storage state by simply swapping out the current disk with another disk with an older or newer snapshot. A VM can also be cloned by creating a new VM with disks that are made from snapshots of the disks of the original VM. The use of snapshots in these scenarios is however limited to the data on disk. States and data in memory are not reinstated or replicated.
Making Custom Images and Data Backup
Here are some example workflows for using images and snapshots with VM instances.
Example 1: Prepare a reusable Linux application image from scratch
Create a boot disk by importing a Linux distro RAW file.
Create a VM instance with the boot disk attached.
Install applications along with any necessary prerequisites, tools, and configurations on the VM.
Shut down the VM instance.
Unset the VM’s boot disk (to allow the disk to be detached).
Detach the boot disk from the VM instance.
Create a snapshot of the boot disk.
Create a new image from the above disk snapshot as the application image.
Example 2: Backup/restore database using snapshots
Create a disk with an installed OS image as the boot disk.
Create a blank disk as a data volume to be used by the database.
Create a VM instance that is attached to the boot disk and the blank disk.
Install the database application along with any necessary prerequisites, tools, and configurations on the VM, with data storage configured to go into the data volume.
Create backup snapshots of the data disk as needed when the VM is in a stopped state.
To restore from an older database snapshot:
Create a disk from the desired snapshot.
Shut down the database application VM.
Detach the existing data disk from the VM and attach the disk created above.
Start the database application.