Instance Actions

Instances are virtual machines that run on the Oxide platform.

Fetch, Update, 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.

Instance attributes are mostly immutable at this time. The only modifications allowed are the designated boot disk, auto-restart policy, and device attachments. Please refer to the instance_update API docs and the sections below for more details about each type of changes.

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.

Related API References

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.

Note
Stopped instances retain their IP addresses but no longer have compute resources (vCPU, memory) allocated to them. To maximize the use of compute resources allocated to your silo, you may choose to shut down idle instances to free up the capacity for other users in the silo.

Related API References

Attach or Detach Disks

Disks can be added to or removed from an existing instance through the Console or API. The instance must be stopped before disk changes can be made. To detach a boot disk, you’ll also need to unset its boot disk designation beforehand.

Detached disks continue to exist until they are explicitly deleted. They can be re-attached to the same instance or other instances.

Important
If no boot disk is set for an instance, attaching or detaching any other disk may invalidate a previously-stable boot configuration. To ensure an instance can boot consistently, confirm that the appropriate disk is set as the boot disk after making disk changes.

Related API References

Add, Modify, Remove Network Interfaces

An instance may have multiple Virtual NICs (VNICS). Each VNIC can belong to a different VPC subnet from the same VPC. The first VNIC created at instance provisioning time is designated as the primary interface. Secondary network interfaces can be added to or removed from the instance via 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 interface is not allowed.

  • Secondary VNICs can only be assigned from subnets in the same VPC as the primary interface.

  • Multiple VNICs from the same subnet are not allowed.

  • The first four IP addresses and last IP address in a subnet are reserved. They cannot be assigned to an instance.

Important
The in-guest network configurations are managed via cloud-init and persisted in settings that may not get re-generated after the first boot. Before you make changes such as setting a different VNIC as the primary interface, please refer to cloud-init documentation and user guides from the distro providers on how to enable the setting changes.

Related API References

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 running or stopped state.

  • An instance may have at most one ephemeral IP, and at most 32 total external IPs.

Note
Removing an external IP will block any existing traffic flows targeting that address, but will not affect other assigned IP addresses. Adding a new address will have no impact on existing traffic.

The semantics of ephemeral and floating IPs are listed in the Networking guide, and examples are provided as part of the Floating IPs guide.

Related API References

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:

  1. Stop the instance (if it is running)

  2. Create a snapshot of the disk you want to resize

  3. Create a disk with the new size, specifying the snapshot as its source

  4. Detach the old disk from the instance and attach the new one

Last updated