AWS

This article refers to Platform v3.3.0. The current Platform version is v3.3.0.

Beta

This platform is newly supported and the integration is currently in Beta. You can follow this guide from start to finish, but you may come across minor issues. If you do, contact our support team and we will resolve them as soon as possible.

Overview

This guide walks you through running Barbara OS on an Amazon EC2 instance using the aws_amd64 image. You turn the factory image into a private AMI in your own AWS account, launch an instance from it, and Barbara OS provisions itself on first boot.

The aws_amd64 image is a UEFI, x86_64, GPT disk image built for the AWS Nitro platform. It ships with the ENA network driver and NVMe storage driver built into the kernel and exposes a serial console, so it boots headless on a Nitro instance and is managed entirely through the Barbara agent — there is no SSH key injection and no cloud-init.

The procedure has five phases:

1. Install the prerequisites in your AWS account.
2. Download the AWS image from Barbara Panel and unzip it.
3. Upload the raw image to Amazon S3.
4. Import the image as a snapshot and register it as a UEFI AMI.
5. Launch the instance, read the Barbara ID from the serial console, and register the node in Panel.

Pre-requisites

• An AWS account with permissions for EC2, Amazon S3, and the VM Import/Export APIs (ec2:ImportSnapshot, ec2:RegisterImage, ec2:RunInstances).
• The AWS CLI v2, installed and configured with aws configure (credentials and a default region).
• An S3 bucket in your target region to stage the image.
• The vmimport service role, required by the VM Import/Export APIs, with read access to your staging bucket. See the AWS VM Import/Export required permissions guide.
• The Barbara OS image for AWS (aws_amd64), downloaded as a .zip from Barbara Panel — see the OS Images view.

Instance requirements

The image only carries the ENA and NVMe drivers and boots in UEFI mode, so it must run on a current-generation Nitro instance (for example the c6i, m6i, m7i, or t3 families). Older Xen-based instance types are not supported.

Strict minimum

• RAM: 2 GB
• Root volume: 32 GB
• vCPU: 2
• Architecture: x86_64

Recommended

• RAM: 4 GB
• Root volume: 64 GB
• vCPU: 2
• Architecture: x86_64

note

The factory image is small. On first boot, Barbara OS creates and expands the user data partition to fill the disk, so choose a root volume large enough for your workloads — the extra space becomes usable storage automatically.

Download the image from Panel

Download the aws_amd64 image from the OS Images view in Barbara Panel (see OS Images view), then unzip it to obtain the raw .img file:

unzip <aws-image>.zip

The archive contains a single raw disk image whose name follows the <device>-<environment>-<version>-<build>.img pattern — for example aws_amd64-pro-4.9.0-1783981297.img. This is exactly the format Amazon S3 and VM Import/Export consume, so no conversion is needed. The commands below use <aws-image>.img as a placeholder; substitute the actual filename.

Upload the image to S3

Copy the raw image to your staging bucket:

aws s3 cp <aws-image>.img s3://<your-bucket>/aws_amd64.img

Import the image as an AMI

VM Import/Export imports the raw disk as an EBS snapshot at the block level, without inspecting the guest operating system, and then you register that snapshot as a UEFI AMI.

1. Import the image as a snapshot:

   aws ec2 import-snapshot \
     --description "Barbara OS aws_amd64" \
     --disk-container "Format=raw,UserBucket={S3Bucket=<your-bucket>,S3Key=aws_amd64.img}"

   The command returns an ImportTaskId.

2. Wait for the import to finish and read the resulting SnapshotId:

   aws ec2 describe-import-snapshot-tasks --import-task-ids <import-task-id>

   Repeat until Status is completed; the SnapshotId appears under SnapshotTaskDetail.

3. Register a UEFI AMI from the snapshot:

   aws ec2 register-image \
     --name barbara-aws \
     --architecture x86_64 \
     --boot-mode uefi \
     --ena-support \
     --virtualization-type hvm \
     --root-device-name /dev/xvda \
     --block-device-mappings "DeviceName=/dev/xvda,Ebs={SnapshotId=<snapshot-id>,VolumeSize=32}"

   The most common parameters to adjust are:

   • --name barbara-aws — pick a name that fits your inventory.
   • --block-device-mappings ... — point SnapshotId at the snapshot from step 2, and set VolumeSize to at least 32. Without it the AMI inherits the snapshot's own size, which is smaller than the minimum, and every instance launched from it would start undersized.

4. Check the AMI before launching anything from it. A missing boot mode or driver flag registers without complaint, and only shows up later as an instance that never boots:

   aws ec2 describe-images --image-ids <ami-id> \
     --query 'Images[0].[BootMode,EnaSupport,BlockDeviceMappings[0].Ebs.VolumeSize,State]' \
     --output text

   Expect uefi, True, at least 32, and available.

Why not import-image?

VM Import/Export's import-image command validates the guest against a list of supported operating systems and rejects custom builds. Barbara OS is a custom build, so use the block-level import-snapshot + register-image path instead.

The import also creates an EBS snapshot that outlives the AMI. Deregistering an image leaves its snapshot in the account, still charged for, so when you retire one, remove both — and read the snapshot ID first, because afterwards the AMI is gone and with it the only link to it:

aws ec2 describe-images --image-ids <ami-id> \
  --query 'Images[0].BlockDeviceMappings[].Ebs.SnapshotId' --output text
aws ec2 deregister-image --image-id <ami-id>
aws ec2 delete-snapshot --snapshot-id <snapshot-id>

warning

Register the AMI in UEFI mode with Secure Boot disabled.

Launch the instance

Launch an instance from the AMI on a Nitro instance type:

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type c6i.large \
  --block-device-mappings "DeviceName=/dev/xvda,Ebs={VolumeSize=64}" \
  --security-group-ids <security-group-id>

• --instance-type c6i.large — any current-generation Nitro type works; size it to your workload.
• --block-device-mappings ... — set VolumeSize (in GB) to the root volume size you want; the data partition grows into it on first boot.
• --security-group-ids ... — the agent only needs outbound connectivity (to the Barbara Panel MQTT broker, the container registry, and the image/OTA storage). No inbound ports are required for normal operation — see From the agent API if you want to query the Barbara ID over the network, which needs an inbound rule.

On first boot, Barbara OS binds its disk encryption to the instance's SMBIOS identity (product_uuid and product_serial), creates the cache and data partitions, and grows data to fill the root volume.

warning

Register the factory image as the AMI and launch each instance from it. The disk encryption key is derived on first boot and tied to that instance's identity, so do not create an AMI from an already-initialized instance's disk and reuse it — the copy stays bound to the original instance and will not decrypt elsewhere.

Retrieve the Barbara ID and register the node

To add the node to Barbara Panel you need its Barbara ID — a unique identifier of the form aws_amd64-<hex>, derived on first boot from the instance's SMBIOS identity. There are two ways to read it: from the on-screen QR code, or from the agent's local API.

From the screen (QR code)

Shortly after boot — once Barbara OS has generated the ID and started its graphical session — the instance's screen shows the Barbara ID together with a QR code. An EC2 instance has no attached monitor, so capture that screen with the instance screenshot:

• In the EC2 console, select the instance and choose Actions → Monitor and troubleshoot → Get instance screenshot, or run:

  aws ec2 get-console-screenshot --instance-id <instance-id> --query ImageData --output text | base64 --decode > barbara-id.jpg

• Open the screenshot and read the Barbara ID from it, or scan the QR code.

Give it a few seconds, and retry if the QR isn't there

The Barbara ID only appears after the agent has started, a few seconds into the boot — an early screenshot may still show the boot console. The screen then rotates between a branded wallpaper and the QR code every 10 seconds, so a single screenshot may catch the wallpaper instead of the code. If you don't see the QR, wait a few seconds and take another screenshot.

From the agent API (programmatic)

Before the node is registered, the agent exposes a small HTTP API on TCP port 18100 that returns the Barbara ID as JSON — useful for scripting onboarding instead of reading a screenshot:

curl -s http://<instance-ip>:18100/device/barbaraId
# {"barbaraId":"aws_amd64-ec2bbd3b27c45214ad5a52bcba003bfb"}

# just the value:
curl -s http://<instance-ip>:18100/device/barbaraId | jq -r .barbaraId

GET /healthz reports whether the API is up ({"status":"ok","apiRunning":true,...}); the agent also serves GET /device/getConfig and GET /network/connectivityCheck on the same port.

Availability and access

• This API is available only until the node is registered in Panel. Once you register it, the API shuts down and the port closes, so query it during onboarding.
• It is unauthenticated. The instance's own firewall already allows 18100, but to reach it from outside you must add an inbound TCP 18100 rule to the instance's security group. Scope that rule to a trusted source IP/CIDR (for example your operator workstation) — never 0.0.0.0/0.

For the full set of ways to find a node's identifier, see Get the Barbara ID of the node.

Summary

You have imported the aws_amd64 image into your AWS account as a UEFI AMI, launched it on a Nitro instance, and let Barbara OS self-provision and bind its encryption on first boot. With the Barbara ID in hand, the next step is to add the node to Barbara Panel.