Skip to content

Instances

Launch instances, stop, start, reboot, resize and terminate them, attach volumes and network interfaces, and read their states.

Updated View as Markdown

An instance is a virtual machine in a project: an instance type, the image it launched from, its SSH keys, a root volume and other volumes, and one or more network interfaces. In the console, open Compute, then Instances.

Launch

In the console, choose Launch instance; with the API, call CreateInstance. Get started walks through a first launch.

Setting Console API field Notes
Name Name name 1–100 characters. Also the guest’s host name, with characters other than letters, digits, . and - replaced by -
Tags Tags tags At most 50. Keys 1–128 characters, values at most 256; keys starting with ezgh: are reserved
Image Image image An image alias, such as linux/ubuntu:24.04, or an exact image ID (img_…): one of the project’s own images or a public EZGH image (API and CLI; the console offers aliases)
Instance type Instance type instanceType Its vCPUs and memory, CPU family and limits
SSH keys SSH keys sshKeyIds 0–10 keys. Without one, only user data can grant access
Network interfaces Network & firewall networkInterfaces The first is the primary. Each entry creates an interface ({ ipv4?, firewallIds? }) or names an available one ({ networkInterfaceId }). Any entry, the first included, may create a private interface ({ subnet, privateIpv4Address?, ipv4?, ipv6?, firewallIds? }; Add private interface, or Primary interface: In a subnet); with a private first entry, no entry is public (Network Gateways)
Firewalls Firewalls, Allow SSH from networkInterfaces[].firewallIds Up to 5 per interface. Omitted: the project’s default firewall; []: none
Root volume Storage, Root volume rootVolume sizeGiB (at least the image’s minimum), volumeType, iops, throughputMBps
Other volumes Add volume, Existing volume volumes Each creates an empty volume ({ sizeGiB, volumeType?, iops?, throughputMBps? }) or names an available one ({ volumeId })
User data Advanced, User data userData At most 16 KiB; base64 in the API. Never recorded in Trails

The launch answers 202 with a CreateInstance operation once the instance’s capacity, volumes, interfaces and firewalls are reserved, and the instance is pending until it boots. A launch that’s refused reserves nothing. With no room for the type, the answer is 409 insufficient_capacity; try again later or choose another type.

What the launch makes, terminating deletes: the root volume, the volumes and network interfaces it created, and the IPv4 addresses those interfaces allocated. Volumes and interfaces you named are detached and kept. Created volumes are named <instance>-root and <instance>-data-<n>.

From the CLI, ezgh compute instances launch takes the same settings as flags: --image, --instance-type, --ssh-key (by name or ID), --tag, --ipv4, --primary-subnet with --ipv4, --no-ipv4, --ipv6 or --no-ipv6, --firewall or --no-firewalls, --network-interface, --subnet and --private-ipv4, --root-size, --root-volume-type, --root-iops, --root-throughput, --new-volume <GiB>[:<type>], --volume, --user-data <file> and --bot (to give the instance access to EZGH). --wait waits until the instance is running:

ezgh compute instances launch web-1 --instance-type <type> --image linux/debian:13 \
  --root-volume-type <volume type> --root-size 50 --new-volume 200 --ssh-key laptop --ipv4 --wait

The console’s Allow SSH from: Anywhere attaches a firewall named ssh-anywhere, creating it the first time, which allows TCP port 22 from any address.

States

State Meaning
Pending Launching
Running Running
Rebooting, Stopping, Starting, Resizing, Terminating Changing, as an operation runs
Stopped Stopped: its volumes, interfaces and addresses stay
Impaired EZGH Cloud can’t reach the instance to act on it. Only terminate is accepted. It may keep running
Recovering Restarting after a hardware failure. Only terminate is accepted
Failed The launch didn’t finish, and what it reserved was released. Terminate it

statusReason (in the console, the state’s tooltip) gives a code and message when there’s more to say, such as instance_initiated_shutdown when the guest powered itself off, instance_crashed, or launch_failed. A terminated instance is gone once its terminate finishes.

A launch EZGH Cloud refuses ends Failed with cell_refused. An instance that stays Failed for 7 days is terminated automatically, with its delete-on-termination volumes.

Status checks

Every running instance has two status checks, in the console’s Status checks column and tab, in ezgh compute instances get, and as statusChecks on the instance:

Check Covers Who fixes it
System The host the instance runs on, its virtual machine process, and its volumes (I/O errors, or I/O stalled for 30 seconds or more) EZGH Cloud
Instance The guest operating system: it answers network probes on its primary network interface, and its kernel hasn’t panicked You

Each check is passed, failed, initializing (up to 3 minutes after the guest boots, until it first answers), not_applicable (the instance isn’t running, or the system check failed so the guest can’t be seen) or unknown (EZGH Cloud can’t currently tell).

  • Network probes are ARP for the interface’s IPv4 address and an ICMPv6 echo to all nodes on the link, sent every 10 seconds; the check fails after 3 unanswered rounds. A guest that disables its interface, ignores ARP or drops multicast echo on every family fails it.
  • Kernel panics are reported by the pvpanic device. EZGH Cloud never stops or restarts the instance for a panic: the guest’s own kernel.panic setting decides whether it reboots or hangs. Guests that load a crash kernel with kdump report no panic unless they set crash_kexec_post_notifiers. Instances launched before status checks existed get the device the next time they’re stopped and started.
  • Watchdog resets appear as events. The guest has an Intel TCO watchdog; it resets the guest only if the guest has a driver for it and runs a watchdog (for example systemd’s RuntimeWatchdogSec). The stock Ubuntu and Debian cloud kernels don’t ship iTCO_wdt (install linux-modules-extra-$(uname -r) on Ubuntu), and Rocky also needs lpc_ich.

Status checks only report: a failed check doesn’t change the instance’s state or start any action. A guest whose kernel hung or panicked can’t act on a normal reboot, which only asks it to: recover it with a forced reboot (ezgh compute instances reboot <instance> --force). Every change is a health event, kept for 30 days (the tab’s events list, ezgh compute instances health-events, or GET …/instances/:instance/health-events). To be alerted, set an alert on the status check metric.

Actions

Action Console API In state Notes
Stop Stop StopInstance Running Asks the guest to shut down and powers it off after 120 seconds. force: true powers it off at once
Start Start StartInstance Stopped 409 insufficient_capacity when there’s no room for its type
Reboot Reboot RebootInstance Running Asks the guest to reboot. force: true resets it without asking
Resize Resize ResizeInstance Running or stopped Changes the instance type. A running instance restarts with the new type
Terminate Terminate TerminateInstance Any Always accepted; cancels any open operation on the instance
Rename, retag Settings tab UpdateInstance Any Synchronous

From the CLI, the instance is given by name or ID. --wait waits for the operation to finish:

ezgh compute instances stop web-1 --wait
ezgh compute instances start web-1 --wait
ezgh compute instances reboot web-1 --force
ezgh compute instances resize web-1 <type> --wait
ezgh compute instances terminate web-1 --yes
ezgh compute instances update web-1 --name web-2 --tag env=prod

Stop, start, reboot, resize and terminate answer 202 with an operation. One operation runs on an instance at a time: another is 409 operation_in_progress. An action in the wrong state is 409 instance_not_running or 409 instance_not_stopped, and an impaired or recovering instance takes only terminate (409 instance_impaired).

Attach and detach

An instance can take more volumes and network interfaces, up to its type’s limits, and give back the ones it doesn’t boot from, with the console, the API or the CLI. Volumes attach and detach while the instance is stopped or running; network interfaces only while it’s stopped.

API Body Notes
AttachVolume { volumeId, deleteOnTermination? } An available volume in the project. deleteOnTermination defaults to false
DetachVolume { volumeId, force? } The root volume can’t be detached (409 root_volume). force is for a running instance (below)
AttachNetworkInterface { networkInterfaceId, deviceIndex? } An available interface in the project. It keeps its firewalls
DetachNetworkInterface { networkInterfaceId } The primary interface can’t be detached (409 primary_interface)

On a stopped instance they’re synchronous and answer 200 with the instance; the guest sees the change at its next start. A network interface change on a running instance is 409 instance_not_stopped. Past the type’s limits is 409 volume_limit_exceeded (limits.volumes counts the root volume; see Instance types) or 409 interface_limit_exceeded. A private interface in a subnet the instance already has one in is 409 subnet_conflict, and one in another VPC whose IPv4 range overlaps is 409 vpc_range_conflict (see VPCs).

ezgh compute instances attach-volume web-1 vol_1m2x7q4b8c3k --delete-on-termination
ezgh compute instances detach-volume web-1 vol_1m2x7q4b8c3k
ezgh compute instances attach-network-interface web-1 eni_7hq2m0x9ka3c
ezgh compute instances detach-network-interface web-1 eni_7hq2m0x9ka3c

Volumes on a running instance

On a running instance, AttachVolume and DetachVolume answer 202 with an AttachVolume or DetachVolume operation, and the guest sees the change without a restart. The instance’s volumeHotplug is true when it can take them. An instance launched before attaching to running instances was available answers 409 instance_restart_required (“Stop and start the instance once to attach or detach volumes while it runs.”) until it’s stopped and started once; a reboot isn’t enough.

  • Attach. Once the operation succeeds, the guest has the disk as /dev/disk/by-id/virtio-vol_…, the volume’s ID (for example /dev/disk/by-id/virtio-vol_1m2x7q4b8c3k). Use that path rather than /dev/vdb: the vd letter depends on the order disks were added. Attaching a volume that’s already attached answers 200 with the instance, and one still attaching answers 202 with its open operation.
  • Detach. Unmount the volume’s file systems in the instance first, and remove them from /etc/fstab. The detach asks the instance to release the disk and waits, with no time limit, until it does: the volume shows Detaching (attachment.state: detaching) and stays in use meanwhile. A detach of a volume that’s already detaching answers 202 with its open operation. Stopping the instance completes a waiting detach.
  • Attaches and detaches of different volumes run at the same time, and the instance can be stopped, rebooted or terminated while they run. A start or resize, and a new attach or detach while a stop or reboot runs, is 409 operation_in_progress, which names the operation. A stop during an attach leaves the volume attached; the instance sees it at its next start.

In the console, open the instance’s Storage tab:

  1. Attach volume lists the project’s available volumes. The volume shows Attaching until the guest has it.
  2. Detach on a volume asks you to confirm, reminding you to unmount it first. The volume shows Detaching until the instance lets it go.
  3. A volume that stays Detaching has Force detach, which asks again with the warning below.

A running instance that needs a stop and start first shows “Stop the instance to attach or detach volumes.” in place of the actions.

From the CLI, the volume is given by ID, UUID or name. Without --wait the commands print the operation; with it they wait (10 minutes, or --wait-timeout) and print the instance. A detach that --wait gave up on carries on, and ezgh says how to follow it with ezgh compute operations get:

ezgh compute instances attach-volume web-1 data --wait
ezgh compute instances detach-volume web-1 data --wait
ezgh compute instances detach-volume web-1 data --force --yes

Force detach

force: true (Force detach in the console, --force in the CLI) frees the volume whether or not the instance releases it. Sent while a normal detach waits, it turns that detach into a force detach: the same operation. Once it succeeds, the volume is available and can be attached to another instance. Attaching it to the same instance again answers 409 volume_detaching until the instance lets go of the disk or is stopped; until then it also counts toward the instance’s volume limit. --force asks you to confirm on a terminal; --yes confirms without asking.

Restore a root volume from a snapshot

To launch from a snapshot of a root volume instead of an image, give rootVolume.snapshotId (snp_…) and leave out image (the CLI’s --root-snapshot in place of --image; not in the console). It also needs blockstore.snapshots.restore on the snapshot. The new root volume keeps the snapshot’s volume type and is at least the snapshot’s volume size. The instance boots in UEFI mode, and its image.alias is empty, as it is for a launch from an exact image ID.

Filters

ListInstances filters by status, instanceType and tags, one tag.<key>=<value> parameter per tag that must match:

curl -sS "https://compute-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/instances?status=running&tag.env=prod" \
  -H "Authorization: Bearer $EZGH_API_KEY"

From the CLI: ezgh compute instances list --status running --tag env=prod.

An instance’s addresses are on its network interfaces: ListNetworkInterfaces with ?instance=ins_….

Navigation

Type to search…

↑↓ navigate↵ selectEsc close