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

Using Private Registries With the Torizon Cloud

Introduction​

Unlike the public Docker Hub registry, a container private registry is a storage and distribution system for container images hosted privately, either on-premises or in a cloud environment.

Popular private cloud-based registry solutions include:

In this article, we will leverage the experience of deploying devices with cloud-hosted private images at scale using:

  1. TorizonCore Builder Tool to pre-provide the modules with the authentication credentials needed to pull images from a private registry.
  2. Torizon Remote Updates to update a fleet of devices.
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.

Why Use Private Registries​

  • Protecting Intellectual Property: Public registries make your container images accessible to anyone. While useful for quick evaluations and proofs of concept, this may not be suitable for production. Private registries ensure that only authorized users can access your images.

  • Cloud Governance: Private registries allow granular access control. This is essential to enforce security policies in your organization, ensuring only authorized personnel can push and send updates to your repository.

Typical Workflow​

  1. Create a cloud-based private registry and set up permissions.
  2. Upload a container image to the private registry.
  3. Upload a Docker Compose file to Torizon Cloud using the TorizonCore Builder Tool.
    note

    Docker Compose files contain only a reference to container images. The container content will not be stored in Torizon Cloud.

  4. Get the authentication credentials to be used on the deployed device.
    caution

    Note that some tokens are short-lived. To avoid update failures, ensure the remote device has access to updated tokens before pulling images from private repositories.

  5. Use Torizon Cloud to update the module remotely.
  6. Scale the solution and Enable Multiple Devices.

Development and Evaluation​

During development, the deployed device is available (via SSH, for example), allowing us to authenticate it manually. Therefore, it is straightforward to run a container hosted in a private registry.

To manually input credentials on the deployed device, use the docker login command. The --config tag specifies the folder for saving the config file, as follows:

# docker --config /etc/docker login

Docker saves the credentials to a config file and reads from it to authenticate registry operations. The config file looks like this:

{
  "auths": {
    <registry>: {
      "auth": <auth-token>
      }
  }
}
info

In the host-machine, the config file is located at ~/.docker/config.json.

In the module, the config file is located at /etc/docker/config.json.

The content of both files is essentially the same. For development and evaluation purposes, you can log in to the private registry in the host machine and simply copy the config file to the deployed device (in the appropriate folder location).

Production and Maintenance​

During production and maintenance procedures with Torizon OS, manually authenticating to your private registry is not scalable. For that reason, it is recommended to directly deploy devices with credentials.

Check the Enable Multiple Devices section to learn how to use the TorizonCore Builder Tool to Pre-provision Docker Containers onto a Torizon OS image, and Torizon Remote Updates to update your application.

The same as before, when receiving a docker-compose update, the module looks for authentication credentials placed in /etc/docker/config.json. Providing multiple devices with credentials can be done remotely, Using Torizon Cloud to Update the Credentials .

Prerequisites​

The following prerequisites are required to follow these instructions:

Check the article for your specific Cloud Provider​

AWS Elastic Container Registry (ECR)​

Google Artifact Registry (GAR)​

Azure Container Registry (ACR)​

GitLab Container Registry​

GitHub Container Registry (GHCR)​

DockerHub private tier subscription​

Enable Multiple Devices​

You will most likely work with multiple devices later in development or early production. It would be very tedious to need to docker login, and add credentials to each device individually.

We will solve this by using the TorizonCore Builder Tool and Torizon Remote Updates.

Create a Custom Torizon OS Image With Docker Credentials​

caution

Before proceeding, make sure you have TorizonCore Builder installed on your development machine, as pointed out in this article's Prerequisites section.

You will use TorizonCore Builder to capture these credentials and create a customized Torizon OS image. Since the config.json file is located at /etc/docker, we can isolate the changes and create a new image. The Capturing Changes in the Configuration of a Board on Torizon OS article describes the steps in detail. In summary, the steps include:

  1. Unpack a base Torizon OS Easy Installer image.
  2. Isolate the config.json file in /etc/docker.
  3. Combine the changes with the base image.
  4. Deploy the changes to create a new Easy Installer image.

By the end of this process, you will have a new Toradex Easy Installer image that you can then flash to multiple boards. Any board you flash with this image will have the config.json file with your credentials information in /etc/docker.

From now on, you can push a container update to all of your boards and they should be able to access your private registry.

Using Torizon Cloud to Update the Credentials​

caution

Make sure you have your credentials.zip file from the prerequisites ready.

If your devices are already deployed or you want to update the credentials on those devices, you can use Torizon Cloud.

Once you have your custom Torizon OS image with Docker credentials, you can go ahead and push it to Torizon Cloud. The Signing and Pushing Torizon OS Images to Torizon Cloud article describes the steps in detail. In summary, the steps include:

  1. Unpack a base Torizon OS Easy Installer image.
  2. Isolate the config.json file in /etc/docker.
  3. Commit and merge the changes to merge them into the base image.
  4. Push the changes to your Torizon Cloud account using your credentials.zip.

As you can see the steps are very similar to the previous section. The difference is that, instead of a deploy as the last step, we push the changes to Torizon Cloud.

Once done you will have a custom package on the "Torizon Cloud Dashboard" with your credentials baked in. Then, proceed as follows:

  1. Update with your custom Torizon OS Package. This will add/update the credentials to all your devices.
  2. Update with your custom container update. This will cause all of your devices to update their containers and access any private registry with your newly updated credentials if needed.


Send Feedback!