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

   The agent copies the VM’s data mounts onto one pool sized to the data plus 20%, and at least 50 GiB more, then switches the mounts over. The systemd services that use those mounts restart at the switch.

4. Optimize

   The pool expands and shrinks online, without unmounting, to stay inside its target band.

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 checks again every 15 seconds. 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 a VM that is stopped or has only an OS disk. To come: how Windows VMs appear in the onboarding list
• The list can be up to 60 seconds old.
• A VM you onboarded before keeps its settings when you onboard it again.

• The console shows why: the install script failed, Azure refused the run, there was no progress for 30 minutes, Zoorik can’t reach the subscription, or the agent installed but sent no report within 3 minutes.
• Amoeba tries again after 10 seconds, then waits twice as long each time, up to 5 minutes, 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 7 days.

• Amoeba updates the agent to each new release by itself.
• The installer keeps the last 3 versions on the VM. If a new version fails its health check, it goes back to the previous one.

Virtual machine

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

• The pool is sized to the data on the VM’s data mounts plus 20%, and at least 50 GiB larger than the data.
• A pool of 512 GiB or more has anchor disks, which stay, and elastic disks, which Amoeba adds and removes: 2 anchor disks and 3 to 6 elastic disks, or 1 anchor disk and up to 3 elastic disks when the VM has too few free slots.
• A smaller pool has no anchor disk: 3 to 6 elastic disks of at least 64 GiB on Premium SSD v2, or 128 GiB on Premium SSD and Standard SSD. So a small amount of data gets a pool well above the data plus 20%.
• Amoeba keeps one data-disk slot free for an urgent expand. A pool with no anchor disk and no free slot can’t expand.
• Each VM gets one pool, on one disk type. The pool keeps the type your data sits on today: Premium SSD v2, Premium SSD or Standard SSD. Where the VM’s region or zone doesn’t offer Premium SSD v2, it uses Premium SSD.
• Data on Standard HDD or Ultra Disk moves to Premium SSD v2 or Premium SSD, which costs more. 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. To come: what happens to writes made on the pool if a late check fails after the services restarted The source disks are never written during the switch. Amoeba then tries the switch again, so your services can restart more than once.
• A process that holds a data mount open outside a systemd service can’t be stopped cleanly, so the switch can’t finish.

• During the 48 h soak, “Go back” on Pool → Migration returns the VM to its source disks. The pool’s disks are then detached and deleted. Going back needs the agent connected.
• After the soak, the source disks are deleted and going back is no longer offered. Each source disk leaves a safety snapshot for 7 days. To come: how to restore from a safety snapshot, and who does it
• After going back, “Schedule pool migration” on Pool starts a new move.
• No shrink runs during the soak. Expands can.

• The move pauses when a phase can’t go on safely, for example when 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” or “Go back” appears when it applies.
• A VM Amoeba declines, for example one with too few data-disk slots, shows why and stays on its own disks.

• When the pool is fuller than the band’s top edge.
• When, at its current fill rate, the pool would reach its safety floor within 6 hours.
• At once, when free space falls below the safety floor: 12% of the pool, or 25 GiB if that is more.
• Expands run on their own, in “Auto” and in “Manual”, except while the move is paused after the switch. Then the pool can’t expand, and the only way on is to go back. To come: what you do if a paused pool fills

• Each expand adds one step of capacity: a sixteenth of the pool, at least 64 GiB on Premium SSD v2 or 128 GiB on Premium SSD and Standard SSD, and at most 512 GiB.
• It attaches a new elastic disk while the VM has a free slot. When none is free, it grows an anchor disk in place. The slot Amoeba keeps free is used only for an urgent expand.
• It runs in three steps, Provision, Device add and Verify, while the pool stays mounted.
• To come: typical time from the trigger to the added capacity

• When the pool is less full than the band’s bottom edge.
• Only if, after the disk leaves, the pool is at least 10 points under the top edge (75% with the default band).
• One disk at a time, and one shrink per VM at a time. Only elastic disks are removed.
• Not during the 48 h soak after the switch.
• In “Auto” the shrink starts by itself. In “Manual” it waits for you on Operations.

A shrink is never held back for a missing backup, a short history, the hour of day, a recent shrink or a small saving.

Changes wait until you click “Save”.

• In “Manual”, Amoeba keeps one ready plan per pool, and checks it again every 60 seconds or so.
• 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.
• A shrink can’t be stopped once it starts.

“Go back” is offered during the 48 h soak, and “Resume” on a paused move that can run again. Both are on Pool → Migration.

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. Check your services after the switch, and go back during the 48 h soak if you need to.
4. After the soak, start each shrink 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. EBS bills 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.

• Every 15 seconds: each mount’s path, filesystem type and ID, its used and total size, the devices, LUNs and cloud disk IDs behind it, and the name of 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 the OS is in the Red Hat family, whether btrfs is available, the disks’ sector sizes, kernel features and the Azure Disk Encryption state.
• During a copy: its progress.
• Every 2 seconds 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 a command channel and a governance channel open to it over WebSocket (wss). All three 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, 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: 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 session ends after 30 minutes idle or 12 hours.

During the 48 h soak, “Go back” on Pool → Migration returns the VM to its source disks and deletes the pool’s disks. After the soak, the source disks are gone, and each leaves a safety snapshot for 7 days.

• 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 for up to 7 days, 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 for up to 7 days, 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.