Skip to main content
Version: Torizon OS 7.x.y

Azure Container Registry (ACR)

Introduction​

Azure Container Registry (ACR) is a solution from Microsoft Azure to store Docker and Open Container Initiative (OCI) images.

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 ACR. 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 Azure Cloud Environment​

caution

Please check ACR Roles and permissions and Authenticate with an Azure container registry. to find the set of permissions that better fits your specific application.

  1. Create a private registry: For more information, see Quickstart: Create a private container registry using Azure.
  2. Install the Azure CLI to get the authentication: In this guide, having the Azure CLI on the board is not required. For more information, see Get started with Azure CLI.
  3. Create two Service Principal accounts:
    • One Service Account with full registry management permission for the host machine.
    • Another with read-only permission for the deployed devices (in this guide, we are using acrpull role).
    • For more information, see How to create a service principal.

Get the Authentication Tokens (Host Machine)​

tip

In this guide, we are going to use a Service principal ID. For other authentication methods, please refer to the complete official documentation Authenticate with an Azure container registry.

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

  1. Log in with your Microsoft email account.

    $ az login

  2. To get the authentication <username> and <password>, run the script from the official documentation on how to create a service principal.

    #!/bin/bash
    # This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

    # Modify for your environment.
    # ACR_NAME: The name of your Azure Container Registry
    # SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
    ACR_NAME=$containerRegistry
    SERVICE_PRINCIPAL_NAME=$servicePrincipal

    # Obtain the full registry ID
    ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
    # echo $registryId

    # Create the service principal with rights scoped to the registry.
    # Default permissions are for docker pull access. Modify the '--role'
    # argument value as desired:
    # acrpull:     pull only
    # acrpush:     push and pull
    # owner:       push, pull, and assign roles
    PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
    USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

    # Output the service principal's credentials; use these in your services and
    # applications to authenticate to the container registry.
    echo "Service principal ID: $USER_NAME"
    echo "Service principal password: $PASSWORD"

  3. To save the credentials to be used by docker, run the docker login command.

    • The <username> is the "Service principal ID".
    • The <password> is the "Service principal password".
    • The <registry-url> looks like <registry-name>.azurecr.io.
    $ docker login --username <username> --password <password> <registry-url>

  4. Push the Image to Azure Cloud. The docker push command should be working normally by default, using the host machine Service account. For more details, see docker push in ACR.

Push the Azure Docker-Compose to Torizon Cloud Using TCB​

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 proceed as follows:

  1. Authenticate using the following flag:

    --login-to <repository-url> <username> <password>
    • The <username> is the "Service principal ID".
    • The <password> is the "Service principal password".
    • The <registry-url> looks like <registry-name>.azurecr.io.

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

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

Get the Authentication Tokens (Deployed Device)​

danger

The authentication token from Azure is short-lived and expires after 1 year by default, the expiration date can be set using the Azure CLI.

  1. Run the following command to save the authentication token to /etc/docker/config.json. The <registry-name>.azurecr.io.

    $ docker --config /etc/docker login --username <username> --password <password> <registry-url>

  2. Copy the authentication file (/etc/docker/config.json) from the host machine to the target device and it should be ready to receive an update from the Torizon Cloud.

    This is going to enable this single device to receive an OTA update. Scaling is really simple with torizoncore-builder and Torizon Cloud, check the section on how to enable multiple devices.

For more information on setting up a container update, take a look at the overview article. If you want to learn more, see Torizon Cloud Web Interface.



Send Feedback!