---
title: "Instances"
description: "Launch instances, stop, start, reboot, resize and terminate them, attach volumes and network interfaces, and read their states."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instances

An instance is a virtual machine in a project: an [instance type](/compute/instance-types), the
[image](/compute/images) it launched from, its [SSH keys](/compute/ssh-keys), a root
[volume](/compute/volumes) and other volumes, and one or more
[network interfaces](/private-networks/network-interfaces). In the console, open **Compute**, then
**Instances**.

## Launch

In the console, choose **Launch instance**; with the API, call
[CreateInstance](/compute-api/CreateInstance/). [Get started](/compute/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](/compute/user-data-and-metadata) 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](/private-networks/vpcs#private-network-interfaces) (`{ 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](/private-networks/network-gateways#instances-with-a-private-primary)) |
| Firewalls | **Firewalls**, **Allow SSH from** | `networkInterfaces[].firewallIds` | Up to 5 per interface. Omitted: the project's [default firewall](/compute/firewalls#the-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](/compute#operations) 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`](/cli/reference/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](/compute/instance-bots)). `--wait` waits until the instance is running:

```sh
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](/compute/volumes#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](/observability/alerting) on the
[status check metric](/compute/monitoring#metrics).

## Actions

| Action | Console | API | In state | Notes |
| --- | --- | --- | --- | --- |
| Stop | **Stop** | [StopInstance](/compute-api/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](/compute-api/StartInstance/) | Stopped | `409 insufficient_capacity` when there's no room for its type |
| Reboot | **Reboot** | [RebootInstance](/compute-api/RebootInstance/) | Running | Asks the guest to reboot. `force: true` resets it without asking |
| Resize | **Resize** | [ResizeInstance](/compute-api/ResizeInstance/) | Running or stopped | Changes the instance type. A running instance restarts with the new type |
| Terminate | **Terminate** | [TerminateInstance](/compute-api/TerminateInstance/) | Any | Always accepted; cancels any open operation on the instance |
| Rename, retag | **Settings** tab | [UpdateInstance](/compute-api/UpdateInstance/) | Any | Synchronous |

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

```sh
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`).

> **Caution**
>
> Terminating can't be undone. The console asks you to type the instance's name to confirm.

## 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](/compute-api/AttachVolume/) | `{ volumeId, deleteOnTermination? }` | An available volume in the project. `deleteOnTermination` defaults to `false` |
| [DetachVolume](/compute-api/DetachVolume/) | `{ volumeId, force? }` | The root volume can't be detached (`409 root_volume`). `force` is for a running instance ([below](#force-detach)) |
| [AttachNetworkInterface](/compute-api/AttachNetworkInterface/) | `{ networkInterfaceId, deviceIndex? }` | An available interface in the project. It keeps its firewalls |
| [DetachNetworkInterface](/compute-api/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](/compute/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](/private-networks/vpcs#private-network-interfaces)).

```sh
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](/compute#operations), 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`:

```sh
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.

> **Caution**
>
> Force detaching can lose data the instance hasn't written to the volume, and the instance will see
> I/O errors on it. Use it only when a normal detach is stuck.

## Restore a root volume from a snapshot

To launch from a [snapshot](/compute/snapshots) 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](/compute-api/ListInstances/) filters by `status`, `instanceType` and tags,
one `tag.<key>=<value>` parameter per tag that must match:

```sh
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](/network-api/ListNetworkInterfaces/) with `?instance=ins_…`.

Source: https://docs.ezghcloud.com/compute/instances/index.mdx
