01 February 2023 / Last updated: 01 Feb 2023

BalenaOS AWS Amazon Machine Images now available

balenaOS, the lightweight, robust and reliable Linux-based embedded operating system running on over 100 different boards and designed specifically to run containers is now available to run in Amazon Web Services (AWS) Elastic Compute Cloud (EC2).

These Amazon Machine Images (AMIs) come preloaded with a cloud config application that provisions the instance into balenaCloud on boot when a config.json file is provided via the instance's user data.

Build and release

balenaOS is built using a continuous integration and deployment (CI/CD) system that allows for each change to be automatically tested and deployed. For selected device types, the deployment includes publishing an AMIs to the us-east-1 AWS region, performing sanity checks, and making it publicly available.

Customers can then use these AMIs to create their own EC2 instances. AMIs can also be exported so they can be moved to any other supported AWS region.

Supported device types

AWS AMIs images are currently being deployed for the following device types:

Generic x86_64 (GPT)
Generic AARCH64

If your fleet is running a different but EC2 compatible device type, please contact us through our support channels and we can check whether Amazon Machine Images could be made available for your device type.

Listing available images

Using the AWS EC2 Dashboard

Published balenaOS images can be browsed in the AMI Catalog section on the EC2 Dashboard:

Using the AWS command line interface (CLI)

You can list the available balenaOS AMIs using the following command:

aws ec2 describe-images --filters "Name=name,Values=balenaOS*"

Creating EC2 instances using balenaOS AMIs

balenaOS AMIs only run on AWS Nitro Systems. Please refer to the AWS instance types documentation for a list of compatible instances.

Also, when setting up the instance networking configuration, specifically a subnet and security group, they need to comply with balena's network requirements so that the instance can access essential services and be managed via balenaCloud.

Using the AWS EC2 Dashboard

From the AMI Catalog you can select a balenaOS AMI and launch an EC2 instance as you would for a different Linux distribution.

The user data field in the Advanced details section can be used to provide a balena config.json file as downloaded from the balenaCloud fleet. This will allow the EC2 instance to provision to balenaCloud on boot.

Using the AWS command line interface (CLI)

The following command can be used to create an EC2 instance using one of the AMIs as listed in the section above.

aws ec2 run-instances --image-id ${ami_id} \
                      --count 1 \
                      --instance-type ${instance_type} \
                      --tag-specifications \
                      "ResourceType=instance,Tags=[{Key=Name,Value=test-${instance_name}}]" \
                      "ResourceType=volume,Tags=[{Key=Name,Value=test-${instance_name}}]" \
                      --subnet-id "${subnet_id}" \
                      --security-group-ids "${security_group_id}" \
                      --user-data "file://config.json"

The following parameters need to be provided to the command above:

ami_id: The AMI ID as listed with aws ec2 describe-images.
instance_type: The AWS Nitro instance type. For example m5.large for x86_64 images or a1.large for aarch64 images.
instance_name: Arbitrary name used to tag the images.
subnet_id: The ID of a subnet in your VPC of choice.
security_group_id: The ID of an existing security group.
config.json: A balenaCloud config.json device configuration file downloaded from the balenaCloud fleet dashboard.

Debugging balenaOS EC2 instances

A balenaOS EC2 instance correctly configured with a valid config.json file should appear as online and be accessible via the balenaCloud dashboard after a few minutes.

If that is not the case, please use a config.json configured for development mode and use the EC2 serial console to access to the serial console prompt of your instance. Direct AWS SSH access is not possible, but instances can be accessed via balenaCloud's cloudlink access, either via the dashbaord web console or in development mode using the balena CLI ssh command.

As always, report any problem with this feature through our support channels or forums.

You can find out what other features we have in progress, let us know about what you'd like to see us developing and upvote features on our public roadmap.