AtomOS Docs

Appearance

Migration and volume import ​

Move disks from other hypervisors into AtomOS vaults for use with Electros or the AtomOS GUI. Migration is not a single click for every estate—plan format conversion, network isolation, validation, and cutover.

Supported import formats and drop folders ​

Place source images on the AtomOS host (or on a path reachable for import) under /mnt/elemento-imports/:

Folder under elemento-imports/Format
qcow2/QEMU qcow2
raw/Raw images (confirm with qemu-img info)
vdi/VirtualBox
vhdx/Hyper-V / Windows export
vmdk/VMware

Organise files before calling the import API. Large imports need sufficient free space in the target vault (Storage & vaults).

Import via storage client API ​

Historically, docs used HTTP on the loopback storage client REST port:

/api/v1.0/client/volume/import

Transport on your build:

  • Older references show: http://127.0.0.1:27777/api/v1.0/client/volume/import
  • From AtomOS 0.9, AtomOS services generally use HTTPS; TCP 27777 remains the storage client REST port in the install reference.
  • Do not assume HTTP vs HTTPS or auth headers without checking your release: run atomos-cli --help, inspect service config on the host, and test with curl against loopback using the trust material your install generated.

Examples in the field may require https://127.0.0.1:27777/... with --cacert / insecure skip only in lab—prefer local trust from atomos-cli --generate-cert output paths on the host.

Verify before automation

Script importers that hard-code http:// may fail on 0.9+ hosts. Update playbooks after a test import on one representative node.

Request body (schema) ​

json
{
  "name": "<volume-name>",
  "ip": "<server-ip>",
  "bootable": true,
  "readonly": true,
  "shareable": true,
  "private": true,
  "clonable": true,
  "bus": "sata",
  "alg": "rsync",
  "overlay": true,
  "import_path": "<path-on-server>",
  "benchmark": {
    "read_MB_bw": 0,
    "write_MB_bw": 0,
    "read_iops": 0,
    "write_iops": 0
  },
  "hw_device": null,
  "fs": null,
  "kind": null
}
FieldNotes
nameElemento volume name
ipServer that holds the source image (often the AtomOS host IP on the storage network)
import_pathFull path to the image on that server
overlaytrue for vmdk, vdi, vhdx; false for raw and qcow2
algTransfer algorithm (documented example: rsync)

After import, the backing file may stay linked until the first unexport. Then compact the overlay into a standalone qcow2.

Overlay compaction ​

Endpoint (same transport caveats as import):

/api/v1.0/client/volume/overlay/compact

Historically documented as:

http://127.0.0.1:27777/api/v1.0/client/volume/overlay/compact

json
{ "volume_id": "<volume-id>" }

Compaction can take a long time on large disks—run in a maintenance window and monitor storage service journals (atomos-cli --journal storage 1h).

End-to-end migration workflow ​

mermaid
flowchart LR
  A[Inventory source VMs] --> B[Export disks to supported format]
  B --> C[Copy to elemento-imports or import_path]
  C --> D[API import into vault]
  D --> E{overlay format?}
  E -->|yes| F[Use VM then unexport]
  F --> G[overlay/compact]
  E -->|no| H[Attach in Electros]
  G --> H
  H --> I[Validate on isolated network]
  I --> J[Cutover]
  1. Inventory — guest OS, disks, NICs, licenses, and dependencies.
  2. Export — vendor export to qcow2/raw/vmdk/vdi/vhdx as appropriate; verify with qemu-img info where applicable.
  3. Transfer — secure copy to the host; scan for malware if sources are untrusted.
  4. Import — call volume import; note volume id for compaction if needed.
  5. Validate — boot on isolated VLAN; install VirtIO if needed; run application tests.
  6. Cutover — adjust DNS/load balancers; decommission source after retention period.
  7. Backup — first successful boot on AtomOS should enter your backup policy.

Assisted migration ​

For larger estates (OVF/OVA bundles, Hyper-V fleets, Proxmox exports, multi-TB chains):

  • Maintain a migration inventory and rollback plan.
  • Convert or import in waves; keep source VMs read-only until validation completes.
  • Engage Elemento for assisted migration or PoC: sales@elemento.cloud.

Concurrent operations

Avoid conflicting volume or VM operations from Electros and manual API calls at the same time—wait for one import or lifecycle action to finish before starting another on the same vault (VMs & Electros).