Version: Torizon OS 7.x.y

AWS Elastic Container Registry (ECR)

Introduction

Amazon Elastic Container Registry (ECR) is the Docker container registry solution from AWS.

In this article, we will use the TorizonCore Builder Tool to authenticate and pre-provide the target devices with a private container image hosted in ECR.

This guide assumes you have followed the steps in the Private Registry Introduction and Prerequisites.

Disclaimer

This guide offers a general guideline for further development and, therefore, should always be adapted to your specific use case.

In real-world scenarios, ensure you set up the appropriate access control, authentication and permissions.

Set Up the AWS Cloud Environment

warning

Please check Private repository policies and policy examples to find the set of permissions that better fits your specific application.

Create a private registry. For more information, see Getting started with Amazon ECR.
Create two IAM users:
- One with full registry management permission for the host machine.
- Another with read-only permission for the deployed devices (in this guide, we are using AmazonEC2ContainerRegistryReadOnly).
Remember to take note of the credentials. It will be used to authenticate the user.
Install the AWS CLI. In this guide, installing the AWS CLI on the board is not required. For more information, see Getting started with AWS CLI.

Get the Authentication Tokens (Host Machine)

tip

In this guide, we will use an authorization token. For other authentication methods, see Private registry authentication.

To get the authentication tokens on the host machine, proceed as follows:

In the host machine, log in with the host machine AWS Access Key ID and AWS Secret Access Key.
```
$ aws configure
```
To save the credentials to be used by docker, run the docker login command.
- The <username> is "AWS".
- The <registry-url> looks like <aws_account_id>.dkr.ecr.<region>.amazonaws.com.
```
$ aws ecr get-login-password | docker login --username <username> --password-stdin <registry-url>
```
Push the image to AWS. The docker push command should be working normally by default, using the host machine Access Keys. For more details, see docker push in ECR.

Push the AWS Docker-Compose to Torizon Cloud Using TCB (Host Machine)

tip

It is a best practice to canonicalize the version of the docker-compose file before pushing it to Torizon OTA.

To use torizoncore-builder platform push with private repositories, we need to authenticate using the following flag:

--login-to <repository-url> <username> <password>

To get the <password>:

Login using the deployed device AWS Access Key ID and AWS Secret Access Key in the host machine.
```
$ aws configure
```
Run the get-login-password command.
```
$ aws ecr get-login-password 
```

Push the docker-compose file to Torizon Cloud. If you are missing <path-to-credentials.zip>, please check the prerequisites.

$ torizoncore-builder platform push \
--credentials <path-to-credentials.zip> \
--login-to <registry-url> <username> <password> \
--canonicalize \
<path-to-dockercompose.yml>

Authenticate the Deployed Device

danger

The authentication token from AWS is short-lived and expires after 12 hours.

To handle token refresh on deployed devices, we can use the Amazon ECR Credential Helper.

Download and Configure the Amazon ECR Credential Helper

Download the latest release. Select the ARM64 version (linux-arm64/docker-credential-ecr-login).
- https://github.com/awslabs/amazon-ecr-credential-helper/releases
Create a new folder /etc/bin and move the executable there.

tip
Using the /etc folder allows the use of the capture changes feature of torizoncore builder later.

Make the file executable.

chmod +x /etc/bin/docker-credential-ecr-login

Edit the docker configuration to use the Credential Helper instead of docker credentials.

note
Check other options here https://github.com/awslabs/amazon-ecr-credential-helper?tab=readme-ov-file#docker
```
nano /etc/docker/config.json
```
```
{
"credsStore": "ecr-login"
}
```

Configure the AWS Credentials

Create a new folder /etc/.aws and create a new file /etc/.aws/env
tip
Using the /etc folder allows the use of the capture changes feature of torizoncore builder later.
```
mkdir /etc/.aws
nano /etc/.aws/env
```

Use the read-only credentials created for the deployed device.

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=***
AWS_REGION=***

Configure Aktualizr

To make the Amazon ECR Credential Helper and the AWS credentials available to the Torizon OTA service, we need to pass some environment variables to the service.

Edit the service.
```
sudo systemctl edit aktualizr-torizon
```

Add the PATH and EnvFile in the correct place.

### Editing /etc/systemd/system/aktualizr-torizon.service.d/override.conf
### Anything between here and the comment below will become the contents of the drop-in file

[Service]
Environment="PATH=/etc/bin:/sbin:/bin:/usr/sbin:/usr/bin"
EnvironmentFile=/etc/.aws/env

### Edits below this comment will be discarded

Restart the service.

sudo systemctl restart aktualizr-torizon

Sanity check. Replace with the correct values.

sudo su
echo "<aws_account_id>.dkr.ecr.<region>.amazonaws.com" | AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> AWS_REGION=<AWS_REGION> /etc/bin/docker-credential-ecr-login get

It should be ready to receive an update from Torizon Cloud.

This enables that single device to receive an OTA update.

Enable Multiple Devices

Scaling is simple with torizoncore-builder and Torizon Cloud, check the section on how to enable multiple devices.

Introduction​

Set Up the AWS Cloud Environment​

Get the Authentication Tokens (Host Machine)​

Push the AWS Docker-Compose to Torizon Cloud Using TCB (Host Machine)​

Authenticate the Deployed Device​

Download and Configure the Amazon ECR Credential Helper​

Configure the AWS Credentials​

Configure Aktualizr​

Enable Multiple Devices​