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 --waitThe 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.panicsetting decides whether it reboots or hangs. Guests that load a crash kernel with kdump report no panic unless they setcrash_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 shipiTCO_wdt(installlinux-modules-extra-$(uname -r)on Ubuntu), and Rocky also needslpc_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=prodStop, 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_7hq2m0x9ka3cVolumes 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: thevdletter depends on the order disks were added. Attaching a volume that’s already attached answers200with the instance, and one still attaching answers202with 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 answers202with 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:
- Attach volume lists the project’s available volumes. The volume shows Attaching until the guest has it.
- Detach on a volume asks you to confirm, reminding you to unmount it first. The volume shows Detaching until the instance lets it go.
- 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 --yesForce 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_….