AosEdge VM Infrastructure

Introduction

Deploy AosEdge host VMs and AosEdge units from one CLI tool.

Features

Manage host VMs and units on VirtualBox, AWS, or Azure. Deploy and provision with aos-virt-unit; run cleanup when needed.

---

Prerequisites

Requirement	Applies to
Python 3.10+	Every deployment
SSH key pair AosEdge_key / AosEdge_key.pub in ~/.ssh/ (Linux) or %USERPROFILE%\.ssh\ (Windows)	Every deployment
Packer 1.12+ on PATH	Every deployment (builds host images)
aos-prov + OEM cert ~/.aos/security/aos-user-oem.p12 (Linux) or %USERPROFILE%\.aos\security\aos-user-oem.p12 (Windows)	AosCloud provisioning — Set up your host, get access
VirtualBox 7.1.10+	VirtualBox deployments
AWS account + credentials	AWS deployments
Azure CLI + subscription	Azure deployments

---

How to deploy

1. Set up the Aos SDK environment

Follow Set up your host. That guide creates the SDK venv and installs CLI tools (including aos-prov).

2. Install aos-virt-unit

Install this tool into the same venv:

Linux:

~/.aos/venv/bin/pip install aos-virt-unit

Windows (PowerShell):

& "$env:USERPROFILE\.aos\venv\Scripts\pip.exe" install aos-virt-unit

Later steps use the same venv binaries by full path (no need to activate the venv).

3. Create a project

Pick a folder where you want this deployment to live, cd there, then run init:

Linux:

cd ~/my-aos-deployment
~/.aos/venv/bin/aos-virt-unit init

Windows (PowerShell):

cd "$env:USERPROFILE\my-aos-deployment"
& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" init

That folder becomes your project — everything for this deployment stays in it:

./
├── config.yaml      # edit before deploy (step 4)
└── artifacts/       # logs and images (filled in by deploy)

Use the same folder for deploy and cleanup.

4. Edit config.yaml

init creates config.yaml from the default example template config.example.yaml (multi-provider sample). The example below shows one local VirtualBox deployment (main + secondary unit nodes) with AosCloud registration. Adjust or add more entries under deployments as needed.

Example config.yaml:

unit_config: &unit_config
  unit:
    node_configs:
      - name: main
        cpu: 1
        mem: 3G
        ip: 10.0.0.100
        uefi: true
        image: "main.qcow2"
        arch: "amd64"
      - name: secondary
        cpu: 1
        mem: 3G
        uefi: true
        image: "secondary.qcow2"
        arch: "amd64"

aos_core_images: &aos_core_images
  url: https://github.com/aosedge/meta-aos-vm/releases/download/v5.2.2/aos-vm-image-qemux86-64-5.2.2.tar.xz

virtualbox: &virtualbox
  build_vm:
    url:   # optional; leave empty to build with Packer, or set an HTTPS .vmdk URL to skip Packer
    name: build_vm
    cpu: 2
    ram: 2GB
    ubuntu_image_url: https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.ova
  host_vm:
    cpu: 4
    ram: 10GB
    disk: 20GB

run:
  type: sequential
  max_workers: 1
  fail_handling_mode: continue

deployments:
  - deployment_name: "my-local-host"
    deployment_type: virtualbox
    provider_config: *virtualbox
    aos_core_images: *aos_core_images
    unit_config: *unit_config
    provision_unit: true

For AWS or Azure, change deployment_type and provider_config, set cloud IDs/regions in config.yaml, and complete cloud credentials before deploy. Full templates: config.example.yaml. Field reference: Config reference.

5. Before deploy

VirtualBox: leave enough disk space under artifacts/. VT-x/AMD-V in firmware is optional; enabling CPU virtualization can improve performance for unit QEMU nodes on the host VM.

AWS or Azure: Cloud credentials and matching fields in config.yaml.

6. Deploy

Linux:

~/.aos/venv/bin/aos-virt-unit deploy

Windows (PowerShell):

& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" deploy

The tool builds or reuses the host image, starts the host VM, downloads the unit image archive (.tar.xz), starts unit nodes, and provisions.

7. Clean up (if needed)

Linux:

~/.aos/venv/bin/aos-virt-unit cleanup virtualbox --single-host-vm

Windows (PowerShell):

& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" cleanup virtualbox --single-host-vm

Run from the same directory as deploy. Other providers:

Linux:

~/.aos/venv/bin/aos-virt-unit cleanup aws --all
~/.aos/venv/bin/aos-virt-unit cleanup azure --deployment-name <name>
~/.aos/venv/bin/aos-virt-unit cleanup

Windows (PowerShell):

& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" cleanup aws --all
& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" cleanup azure --deployment-name <name>
& "$env:USERPROFILE\.aos\venv\Scripts\aos-virt-unit.exe" cleanup

Add --force to skip the confirmation prompt on any platform.

---

Cloud credentials (AWS and Azure)

AWS (example)

Linux:

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_DEFAULT_REGION="eu-central-1"
aws sts get-caller-identity

Windows (PowerShell):

$env:AWS_ACCESS_KEY_ID     = "your-access-key-id"
$env:AWS_SECRET_ACCESS_KEY = "your-secret-access-key"
$env:AWS_DEFAULT_REGION    = "eu-central-1"
aws sts get-caller-identity

Azure (example)

The Azure CLI commands are identical on both platforms:

az login
az account set --subscription "<SUBSCRIPTION_ID>"
az account show

<SUBSCRIPTION_ID> must match subscription_id in config.yaml for your azure deployment.

---

Config reference

config.yaml at the project root; optional YAML anchors (&name, *name). Authoritative sample: config.example.yaml.

Layout (overview)

unit_config: &unit_config
  unit:
    node_configs: [ ... ]

aos_core_images: &aos_core_images
  url: <https URL to unit .tar.xz>

virtualbox: &virtualbox
  build_vm: { ... }
  host_vm: { ... }

aws: &aws
  region: ...
  key_pair_name: ...
  # ...

azure: &azure
  subscription_id: ...
  # ...

run:
  type: sequential        # sequential | parallel
  max_workers: 1
  fail_handling_mode: continue   # continue | fail-fast

deployments:
  - deployment_name: "..."
    deployment_type: virtualbox | aws | azure
    provider_config: *virtualbox
    aos_core_images: *aos_core_images
    unit_config: *unit_config
    provision_unit: true | false

run

How deploy processes the deployments list. This is not the CLI command name and not artifacts/run.log. Defaults if omitted: sequential, max_workers: 1, continue.

Field	Required	Description
type	no	sequential or parallel.
max_workers	no	Maximum deployments in parallel when type is parallel; integer ≥ 1.
fail_handling_mode	no	continue or fail-fast.

deployments

Each item = one host VM + one unit.

Field	Required	Description
deployment_name	yes	Host label (EC2 name, Azure computer name, etc.). Azure: ≤ 64 chars; no spaces or these characters among others: `_ \
deployment_type	yes	virtualbox, aws, or azure.
provider_config	yes	Provider block — see virtualbox, aws, azure.
aos_core_images.url	yes	HTTPS .tar.xz of unit QEMU images (meta-aos-vm releases).
unit_config	yes	unit.node_configs — see unit_config.
provision_unit	yes	true: needs aos-prov and OEM cert. false: host + unit only, no AosCloud registration.

unit_config

Field	Required	Description
name	yes	Node name; on host often <name>.aos-unit.
image	yes	QEMU image file name.
arch	yes	arm64, amd64, or x86_64; same family per deployment.
cpu	yes	vCPUs for the node.
mem / ram	yes	e.g. 3G, 2GB.
ip	no	Main node only (for now). Default 10.0.0.100. Omit on secondary.
uefi	yes	true for typical meta-aos-vm qcow2 disks.

Provider: virtualbox

Field	Required	Description
build_vm.name	yes	Packer build name (shared across VirtualBox deployments).
build_vm.cpu / ram	yes	Build VM size.
build_vm.ubuntu_image_url	yes	Ubuntu OVA/cloud image URL.
build_vm.url	no	Pre-built .vmdk HTTPS URL — skips Packer if set. Leave empty to build with Packer.
host_vm.cpu	yes	Integer or max (all host cores).
host_vm.ram / disk	yes	Host VM resources.

Provider: aws

Field	Required	Description
region	yes	AWS region.
key_pair_name	yes	EC2 key name in region.
ami_version	yes	AMI reuse label.
architecture	yes	arm64 or amd64 / x86_64.
instance_type_arm / instance_type_amd	yes	Nested-capable types recommended for QEMU units.

Provider: azure

Field	Required	Description
subscription_id	yes	Subscription GUID.
location	yes	Region.
managed_image_resource_group_name	yes	Gallery RG; "" reuses resource_group_name.
shared_image_gallery_name	yes	Gallery name (no hyphens).
resource_group_name	yes	Host VM / network RG.
network_security_group_name	yes	NSG name.
security_rule_name / priority	yes	Unique per shared RG.
virtual_network_name / address_prefix	yes	VNet.
subnet_name / address_prefix	yes	Subnet.
public_ip_address_name	yes	Public IP.
network_interface_name	yes	NIC.
vm_size_arm / vm_size_amd	yes	Nested-capable SKUs for QEMU.
image_arm / image_amd	yes	Marketplace publisher:offer:sku:version.
az_image_disk	yes	Packer builder disk (≥ 30GB for Jammy).
host_vm_image_version	yes	Major.Minor.Patch (e.g. 1.0.0).
architecture	yes	arm64 or amd64.

---

Troubleshooting

Logs (paths are printed when deploy starts):

Log	Contents
artifacts/run.log	Whole run
artifacts/deployments/<deployment_name>/run.log	One deployment

Symptom	What to check
deploy failed or unclear errors	Logs above — start with artifacts/run.log, then the deployment's …/run.log.
Wrong AWS account / API denied	AWS credentials; aws sts get-caller-identity; check AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION (PowerShell: $env:AWS_*).
Azure auth / subscription	Azure credentials; az account show, subscription_id.
VirtualBox / Packer not found	VBoxManage --version, packer version, check PATH / $env:PATH.
SSH failures	Key at ~/.ssh/AosEdge_key (Linux) or %USERPROFILE%\.ssh\AosEdge_key (Windows), key_pair_name (AWS), NSG/firewall.
aos-prov / certificate	Get access; check provision_unit and cert path.
deploy touches unexpected providers	Check every entry under deployments in config.yaml — deploy runs them all.

---

Support

• AosEdge Documentation
• Get access / AosCloud
• aos_vm_infra_assets

---