Amoeba product guide

1. Connect

   Connect your Azure directory once. A script you run in Azure Cloud Shell gives Zoorik’s app a custom role on the subscriptions you choose.

   On AWS, enter your 12-digit account ID, then run a script in AWS CloudShell that creates the IAM role ZoorikStorageOperator. It trusts Zoorik’s AWS account only with your organisation’s external ID.

2. Onboard

   Pick the VMs Amoeba manages. It installs its agent on each one and leaves every other VM alone.

3. Move onto a pool

   Amoeba copies your data onto one btrfs pool, sized to your data with room to grow, while your services run. Then it switches each mount to the pool, with a short restart of the services that use it. Once the switch is checked, it snapshots and deletes each old disk.

4. Optimize

   Amoeba grows the pool before it fills, and sooner when data arrives fast. The pool stays mounted while it changes.

   When your data goes down and stays down, it shrinks the pool one disk at a time. So you pay for close to what you use.

1. Open the console

   To come: the Amoeba console address, and how you sign in

2. Connect Azure

   Click “Connect Azure” and enter your directory (tenant) ID. The console shows a script to run in Azure Cloud Shell. It adds Zoorik’s app to your directory, creates the role “Zoorik Storage Operator”, and assigns it to the app on each subscription you name.

   $ To come: the connect script, exactly as the console prints it

3. Verify

   Click “Verify”. The connection reads “Verifying” until Zoorik can read a subscription through the role, and the console keeps checking. Run Verify again later to add subscriptions you granted since.

4. Onboard VMs

   Click “Onboard VMs”. The list shows each VM Amoeba can onboard, with its resource group, region, size, and the number and total size of its data disks. Tick the VMs you want, then click “Onboard”.

5. The agent installs

   Amoeba installs its agent on each VM through Azure Run Command. The VM’s agent reads “Installing”, then “Connected” once its first report arrives.

6. The move starts

   After the first report, Amoeba plans the pool and starts moving the VM onto it, with no further click.

• The list comes from Azure Resource Graph only. Amoeba doesn’t look inside a VM, or show its used space or savings, until the VM’s agent reports.
• VMs that can’t be onboarded are counted in one line under the list, with the reason. For example, the VM is stopped or has only an OS disk. To come: how Windows VMs appear in the onboarding list
• The list can be a little behind Azure.
• A VM you onboarded before keeps its settings when you onboard it again.

• The console shows why the install failed: the script failed, Azure refused the run, or the install stalled.
• It also says when Zoorik can’t reach the subscription, or when the agent installed but its first report didn’t arrive in time.
• Amoeba tries again, waiting longer each time, for as long as the VM stays onboarded.
• “Reinstall” in Settings starts a new install straight away, or when the current step of the move ends.

The IAM role ZoorikStorageOperator, the pool’s gp3 volumes, and an EBS snapshot of each source volume, kept for a few days.

• Amoeba updates the agent to each new release by itself.
• If a new version fails its health check, the installer restores the previous one.

Virtual machine

Every figure is a value, or a dash that says why it is missing. The dash reads, for example, “Available once the agent reports”, “No Azure price for this disk” or “Agent not reporting”. Amoeba never fills a gap with a guess.

• Amoeba sizes the pool to your data, with room to grow. It looks at your peak use and recent growth, not at the size the old disks were given.
• It picks the cheapest layout of disks that holds your data and carries your VM’s disk load.
• Each VM gets one pool, on one disk type. On Azure the pool uses Premium SSD v2 where your region offers it, and Premium SSD otherwise.
• On AWS the pool uses gp3 volumes, in the instance’s Availability Zone.
• Data on Standard SSD, Standard HDD or Ultra Disk also moves to Premium SSD v2 or Premium SSD. Per GiB, Premium disks can cost more than Standard ones. Zone-redundant (ZRS) disks map to a locally redundant (LRS) pool, so the data loses zone redundancy.

• The agent stops every systemd service that holds a data mount open, with systemctl stop. It never kills a process itself.
• It checks nothing is left to copy, saves /etc/fstab, mounts the pool at each data mount’s path, and starts the services again. Your mount paths stay the same.
• If any step fails, the agent tries to put the original mounts back and start the services again. The source disks are never written during the switch. Amoeba then tries the switch again, so your services can restart more than once.
• To come: what happens to writes made on the pool if a late check fails after the services restarted
• A process that holds a data mount open outside a systemd service can’t be stopped cleanly, so the switch can’t finish.

• A move only goes forward. Once the switch is checked, Amoeba snapshots each old disk, deletes the disk, and keeps the snapshot for a few days before deleting it too.
• A disk is deleted only after its own snapshot succeeded, and only when its tag names this move.
• To come: how to restore from a safety snapshot, and who does it
• You pay for both sets of disks only while the move runs, and then for the snapshots while they’re kept.
• The pool keeps growing before it fills. Shrinks wait until Amoeba has seen enough of your use after the move.

• The move pauses when a phase can’t go on safely. For example, the VM can’t take a pool, a copy fails, or the outcome of the switch can’t be known.
• Pool → Migration shows where it paused and why. “Resume” appears when the move can run again.
• A VM Amoeba declines, for example one with too few data-disk slots, shows why and stays on its own disks.

Amoeba grows the pool before it fills, and sooner when data arrives fast. It also adds room when btrfs needs space for its own metadata.

Expands run on their own, in “Auto” and in “Manual”. The pool can grow during the move too, even while a move is paused.

• The pool stays mounted while it grows, so your services keep running.
• Amoeba grows existing disks in place, or adds new ones while the VM has a free disk slot.
• When data arrives fast, it adds room sooner.
• To come: typical time from the trigger to the added capacity

When your data goes down and stays down, Amoeba shrinks the pool one disk at a time. A shrink waits until the move is done and Amoeba has seen enough of your use.

The new size follows the same rule as a new pool: sized to your data, with room to grow. Amoeba picks the cheapest layout that passes its space, performance, saving and safety checks.

In “Auto” the shrink starts by itself, when the pool is quiet. In “Manual” it waits for you on Operations.

A shrink removes one disk at a time. A large shrink is split into parts.

A running shrink stops when the pool needs room fast. Amoeba never detaches a disk while the pool is close to full.

Changes wait until you click “Save”.

• In “Manual”, Amoeba keeps one ready shrink plan per pool, and keeps it up to date.
• Operations shows it as “Waiting for you”: the disk it removes, what it saves, how full the pool is after, and how much data moves. Overview lists it under “Needs you”.
• “Start shrink” checks again on fresh readings and removes exactly that disk. If the plan has changed, the card refreshes instead.
• If a check fails, the card reads “Can’t shrink now” with the reason, and has no button.
• You can’t stop a shrink once it starts. It stops only when the pool needs room fast.

“Resume” on Pool → Migration starts a paused move again, once it can run. If the switch’s outcome can’t be known, the move waits for you to click Resume. A move only goes forward.

1. Run the free disk assessment first, to see what your own VMs could save.
2. Onboard one VM whose services run under systemd, and set “When Zoorik shrinks” to “Manual” on its Settings page.
3. Watch the move on Pool → Migration, and check your services after the switch.
4. When a shrink waits for you, start it yourself from Operations, and read its log entry.
5. Then switch to “Auto” and onboard more VMs.

• Prices are Azure’s public list prices for the disk type and region, from the Azure Retail Prices API. A month is 730 hours.
• On AWS, prices come from the AWS Price List API. AWS charges EBS per GB-month.
• Standard SSD and Standard HDD are priced on capacity only, without transaction charges.
• Savings are measured against the source disks.
• A saving can be negative, for example when a pool has grown past the disks it replaced. It is shown as it is.
• Where Azure has no price for a disk, the figure reads “No Azure price for this disk”. Until the agent reports, used space and savings read “Available once the agent reports”.

The role is the limit on what Zoorik can do in your Azure. An action added later reaches your subscription only when you run the script again.

On AWS, Zoorik acts only through the IAM role ZoorikStorageOperator, which you create in AWS CloudShell. The role trusts Zoorik’s AWS account only with your organisation’s external ID. Zoorik’s own AWS identity may only assume roles with that name and read AWS prices.

• In each report: each mount’s path, filesystem type and ID, and its used and total size.
• With each mount: the devices, LUNs and cloud disk IDs behind it, and the systemd service that holds it open.
• Disk activity per device: IOPS, latency and throughput, and the 99th percentile of IOPS.
• The pool’s sizes, and its btrfs error counters per disk.
• Host facts: the kernel version, whether btrfs is available, the disks’ sector sizes, kernel features and the Azure Disk Encryption state.
• During a copy: its progress.
• While the VM has a pool: how busy the disks are, the copy’s own reads and writes included.
• If an install fails: the agent’s last log lines, with secrets removed.

The copy itself runs inside the VM, from the source disks to the pool disks.

• The agent sends its reports to Zoorik, and keeps two channels open to it over WebSocket (wss). The reports and both channels use the agent’s own key, from /etc/amoeba-agent.env.
• Zoorik signs every command with that key (HMAC-SHA256), and the agent checks the signature before it acts. A key from another VM can’t act for this one.
• Zoorik reaches the VM through Azure Run Command, to install the agent and to check the move. Azure adds its Run Command extension to a VM that doesn’t have it yet. It keeps a copy of each command and its output under /var/lib/waagent, and records each run in the activity log.
• On AWS, Zoorik reaches the instance through AWS Systems Manager (AWS-RunShellScript), which keeps each command’s history in your account.

New pool disks take the encryption key of the first encrypted source disk. That is your customer-managed KMS key on AWS, or your disk encryption set on Azure. Encryption at rest carries over.

VMs that use Azure Disk Encryption are not moved as they are.

Sign in with a Microsoft or Google account, as for Coral.

A move only goes forward. Once the switch is checked, Amoeba snapshots each old disk and deletes it. It keeps each snapshot for a few days, then deletes it too.

• On the VM: the agent in /opt/amoeba-agent, the service amoeba-agent.service, /etc/amoeba-agent.env, the /etc/fstab backup, and the pool with your data on it.
• In Azure: the pool disks, the safety snapshots while they’re kept, the role “Zoorik Storage Operator” and its assignments, and Zoorik’s app in your directory.
• In AWS: the pool’s gp3 volumes, the safety snapshots while they’re kept, and the IAM role ZoorikStorageOperator.
• Your data stays on the zoorik-amoeba-pool-… disks, and nothing grows them once Amoeba stops, so keep them and watch their free space. Snapshots not yet deleted stay in your account.