12 June 2023 / Last updated: 12 Jun 2023

Using balenaOS Amazon AWS AMIs

Back in February, we wrote a post about the then-new availability of BalenaOS Amazon Machine Images (AMI) for Amazon AWS. In this post, we’ll examine in more detail what AMIs are, why you would want to use them with balenaOS, as well as an example use case you can try out for yourself.

What is an AMI?

We will start out with the assumption that you are already familiar with Amazon Web Services (AWS), an on-demand cloud computing platform available on a metered, pay-as-you-go basis. One of the many services offered by AWS is called Elastic Compute Cloud, better known as EC2. This service provides virtual machines known as “instances” which can be created, launched, and terminated as needed (which is the “elastic” aspect.)

Virtual machines are created on EC2 through the use of an AMI, which is a configuration template that includes an operating system and any additional software needed to deliver a particular service. In the case of balena’s AMI, it includes balenaOS as the operating system, as well as software to provision the instance into balenaCloud upon boot. In other words, when you launch the AMI with your balenaCloud configuration details (more on that below) it shows up as just another device in your balenaCloud dashboard. What type of device it shows up as depends on which AMI you choose to deploy. Balena currently offers two AMIs, one for Generic x86_64 (GPT) and one for Generic AARCH64.

Although some AMIs are private or require an additional fee, the balena AMI is free and publicly available in the AMI Catalog in the EC2 dashboard.

Why use an AMI?

Since balenaOS is primarily used for running containers on embedded or edge devices, you may wonder why anyone would want to create a virtual balenaOS device in the cloud. There are actually many compelling use cases that include:

If you don’t have any hardware available and you want to test or develop with balenaOS or some aspect of it such as the supervisor, kernel, or environment, an AMI is one of the fastest, easiest ways to get started.
If you want to test the fleet features of balenaOS but have limited hardware, you can spin up many devices quickly - and then delete them just as easily to keep costs low and not pay for hardware you ultimately won’t need.
Manage your edge and cloud computing resources with the same familiar balenaCloud interface. This is especially appealing when running a fog computing architecture to process data from edge devices.
Our sample project below is based on this use case.

AMI example project

Although our example project is based on using DIY Balenair devices, you can follow the same setup guide below (in the “AMI setup” section) to create an AMI in any fleet.

Balenair

Last year, we introduced Balenair, a DIY indoor air quality monitor that contains one or more environmental sensors along with a built-in LED display. They provide a visual, color-coded index value that represents the amount of pollution (particulates, CO2, VOC) in the sampled air.

These devices, which include a Raspberry Pi (3A+ or Zero 2W) utilize multiple containers and run on balenaCloud. They are designed to be a great starter project for learning about IoT, containers and the balena platform in general.

Each device runs its own copy of InfluxDB and hosts a comprehensive Grafana dashboard courtesy of our Connector and Dashboard blocks. The web dashboard provides current and historical values for all of the on-board sensors. A single Balenair device can provide air quality readings for a single room. However, due to their relatively low cost, separate ones can be placed in multiple rooms in a home or office. Large installations may have units in multiple offices or even in multiple locations.

The Balenair Aggregator

To make it easier to view data from dozens or hundreds of Balenair devices, we came up with The Aggregator: a device that reads the data from multiple Balenair units and displays them on a single web dashboard, highlighting the ones with readings that are excessively high. The dashboard is dynamic, so as you add and configure more devices, they show up automatically without any further intervention on the AMI.

The Aggregator runs on an x86 or Arm-based device running balenaOS and provides a web interface. Like us, you may have Balenair (or similar) devices located in offices all over the world. However, we want the aggregator to live in the cloud, not tied to a physical device in an office somewhere. A use case such as this is perfect for an AMI.

Note that this is a sample project to get a balena AMI up and running and communicating with devices in a fleet. Use it as a starting point or template for your own projects or ideas. See the security section for considerations that would need to be implemented before placing a project such as this into production.

Getting started

First, check out our comprehensive guide for deploying one or more Balenair devices. You’ll create a balenaCloud account as part of this setup - the first ten devices are free and full-featured! Once you have your air quality monitoring devices up and running, you can deploy [the Aggregator] to an AMI to view a summary dashboard.

First, create a new fleet in balenaCloud for your Aggregator, or simply click the button below:

AMI setup

You’ll need to create an AWS account or login if you already have one. We are going to set up the AMI using the AWS web interface, but advanced users can do the same using the AWS CLI.

First, navigate to the EC2 service after clicking “all services”:

Once on the EC2 page, click on the “AMI Catalog” under “Images” on the left side menu. Make sure the “us-east-1” region is selected in the upper right dropdown. (Displays as “N. Virginia”) On the right side panel, enter balena in the AMI search field, and click on “Community AMIs”. You should see a list of all available balena AMIs. Click the “Select” button next to the most recent version available for amd64.

Once you have selected the AMI, the “Launch Instance with AMI” button near the top of the page will become enabled, so click it. You’ll then be on the “Launch an instance” page with a set of fields to fill out - but don’t worry, it’s easy and we’ll walk you through it.

Enter a name for the “Name and tags” section.

“Instance type” will determine the memory and CPU available to your virtual device. The instance types that are not supported by the balena AMI will be grayed out in the dropdown list. However, the balenaOS AMIs currently require at least 3GB of memory (we expect this to be reduced in the future) so for this project select the “t3.medium” which provides 4GB of memory.

For “Key pair” select “Proceed without a key pair (Not recommended)” - we will use balenaCloud, so a key pair is not required.
For “Network settings” uncheck “Allow SSH traffic from” - we’ll ssh via the balenaCloud dashboard terminal instead.

For “Storage”, you can leave the default disk size of 8GB. (But feel free to add more if you think you’ll need it!)

In “Advanced details”, click the right arrow to expand the fields and scroll down to the “User data” text box. This is where we will associate the AMI with our fleet in balenaCloud by entering our balena device configuration details. To obtain this data, go to your Aggregator fleet in your balenaCloud dashboard and click the “Add device” button. At the bottom of the “Add new device” dialog, select “Download configuration file only” from the “Flash” dropdown and click the button to download a config file. (You can leave all the form field selections at their default values)

Copy the contents of this downloaded config file (including the starting and ending curly brackets) and paste them into the “User data” field in the AWS form.

Scroll to the bottom of the page and click “Launch Instance” - note that billing at the rate selected earlier will commence at this point until you terminate the instance.

If you view the “Instances” page on AWS, within a minute or so you should see the instance running if all went well:

Then, head back over to your balenaCloud dashboard, and the virtual device should be showing as “online”.

Congratulations! You now have a new balena device in the cloud that acts just like a physical device that you can ssh into, reboot, push code to, use the public URL, or any other feature exposed by the platform.

In fact, the Aggregator software we pushed to the fleet earlier should already be uploading to the device. (Note that you may need to reboot your instance via the balenaCloud dashboard for all services to show up and initialize.) Once it’s running, we’re ready to configure our Aggregator…

Adding Balenair devices

For each balenair device we want to monitor in our Aggregator, we’ll need to tell it the address of our AMI. In the AMI’s balenaCloud dashboard, note the “PUBLIC IP ADDRESS”:

Then, for each Balenair device that you want to monitor, in its balenaCloud dashboard add a device variable named AGG_ADDRESS with the value equal to the IP address of your AMI.

You could also add this as a fleet variable to point your entire fleet to the aggregator.

Note that AWS will release the IP address of your instance when it is stopped, hibernated, or terminated. In that case, your AMI will be assigned a new IP address which you will need to update on your Balenair devices.

Open the port

There’s one more task required before we can view our Aggregator’s dashboard: open the port on our AMI so it can communicate with the Balenair devices over MQTT. In the AWS EC2 dashboard, click on “instances” then click on the link for your instance ID:

Then, scroll down in the instance summary screen and select the “Security” tab. Finally, click on your “security group” which will likely have a long, unpronounceable, random name.

When your security group page loads, click on the “Edit inbound rules” button at the bottom of the page, and then click add rule to add the following: A “Custom TCP” for port 1883.

Finally, click on the “Save rules” button.

Viewing the aggregated dashboard

To view the dashboard, go to your AMI’s balenaCloud dashboard page, and click the button to enable the “PUBLIC DEVICE URL”:

You’ll then have a blue link that will take you to your new dashboard hosted on your balena AMI!

Security considerations

This project is mainly intended as an introduction to the use of AMIs with balena. The Aggregator project as implemented here communicates with Balenair devices using unencrypted MQTT which could potentially be intercepted by a third party. If you implement this beyond an experimental phase, we suggest you:

Add a username and password to the Aggregator dashboard by clicking on the “Sign In” button on the lower left part of the screen. The initial username and password are admin.
Add usernames and passwords to the Mosquitto broker and don’t allow anonymous users. (See the authentication section of the Mosquitto man page for more information.)

Use TLS and/or payload encryption between the client and the AMI. The Balenair devices (clients in this case) do not yet support this, but if you are implementing a similar solution on your own, it should be considered.

Some of these topics are discussed in more detail in the Aggregator Github repository with links to additional security resources.

Final Thoughts

Using an AMI with balenaCloud can be a convenient option for a number of use cases. For as little as $0.04 per hour you can quickly and easily spin up an EC2 instance and enjoy almost all of the benefits of a physical device in your balena fleet.

Have you had success following our sample guide? What use cases have you found for AMIs on balena? As always, we welcome feedback, suggestions, and comments in our forums.