Instances are virtual machines that run on the Oxide platform.
Fetch or Delete Instances
Instances can be retrieved by instance id, name, or project using the web console, API, or CLI. Because instance names are unique within the scope of a project but not globally, when fetching by instance name, the project name is required as well. See the Resource Identifiers guide for more information.
Instances no longer in use can be deleted once they are in the stopped
state. Terminating a VM does not result in deletion of the disks associated with it. Its disks are detached and remain intact.
Start, Stop, Reboot Instances
Instances can be started, stopped, or rebooted via Oxide Console, API, or CLI commands. Stop
and Reboot
are meant for situations when the instances can only be acted on outside the guest operating system or when graceful shutdown is not required.
Unlike invoking a shutdown from within the instance, the stop
command issues a halt request to the guest operating system. The process does not coordinate with software running in the instance.
The reboot
command resets the guest by pausing all devices, resetting them to their cold-boot states, and then resuming the devices. This also does not result in a graceful shutdown and restart.
Attach or Detach Disks
Disks can be added to or removed from an existing instance through the Console or API. Instances must be in the stopped
state before a disk can be attached or detached.
Detached disks continue to exist until they are explicitly deleted. They can be re-attached to the same instance or other instances.
Add, Modify, Remove Network Interfaces
The network interfaces of an existing instance can be modified through the Console or API.
There are several restrictions on network interface assignments and changes:
The instance must be in the
stopped
state for any network interface changes.Removal of a primary NIC is not allowed.
Multiple NIC from the same subnet is not allowed.
The first four IP addresses and last IP address in a subnet are reserved. They cannot be assigned to an instance.
Any external IP address assigned to the instance is attached to the primary NIC. It can only be removed along with the NIC once another NIC is set as primary.
Attach or Detach External IP Addresses
The external IP addresses assigned to an instance can be modified through the API.
The instance must be in the
started
orstopped
state.An instance may have at most one ephemeral IP, and at most 32 total external IPs.
The semantics of ephemeral and floating IPs are listed in the Networking guide, and examples are provided as part of the Floating IPs guide.
Resize Instances or Disks
The size of an instance, as defined by its vCPU count and memory size, cannot be changed after the instance is created. The only way to resize an instance currently is to stop it, detach its disks, and attach them to a new instance of the desired size. The data on disk will remain intact, but the instance’s in-memory data and network states will not carry over.
For instances that need stable IP addresses, you can use floating IPs so that the addresses can be retained across resizing.
Disk resizing is also unsupported at this time, but you can create a larger disk based on an existing disk:
Stop the instance (if it is running)
Create a snapshot of the disk you want to resize
Create a disk with the new size, specifying the snapshot as its source
Detach the old disk from the instance and attach the new one