torizoncore-builder can generate a canonical copy of the used docker-compose file as described here.
Canonicalizing a docker-compose file basically means putting it into a specific YAML format, removing comments (lines starting with a # or any word included after a # character), and associating HASH values to Docker images.
If I’m right, associating the hash works replacing tha tag
I’ve just found that the official docker compose config has the option --resolve-image-digests (or the similar --lock-image-digests) to pin image tags to their immutable digests.
The approach is quite similar, but the result is a little bit different: the sha is appended to the tag (not replaced).
I might make mistakes or occasionally get you wrong. Our support team will step in if needed.
Canonical Docker Compose Files in TorizonCore Builder
You’re correct about how TorizonCore Builder canonicalizes Docker Compose files. The documentation confirms that “canonicalizing a docker-compose file basically means putting it into a specific YAML format, removing comments (lines starting with a # or any word included after a # character), and associating HASH values to Docker images”(1).
Current Toradex Implementation vs Docker’s Official Approach
Your observation about the difference between the two approaches is accurate:
Toradex canonical format: Replaces the tag with the SHA digest
Docker’s official format: Appends the SHA digest to the tag
Benefits and Considerations
The documentation doesn’t provide specific rationale for why Toradex chose the “SHA only” approach over the “tag + SHA” format. However, both approaches achieve the primary security and reproducibility goals:
Immutable image references: Both formats ensure that the exact same image is pulled every time
Security: Both prevent tag mutation attacks where malicious actors could push new content to an existing tag
Reproducibility: Both guarantee consistent deployments across environments
Compatibility with Torizon Cloud
The current canonical format is specifically designed to work with Torizon Cloud’s offline update capabilities(1). The --canonicalize option in platform push generates this format specifically for Torizon Platform Services(2).
Future Considerations
While the Docker official format might offer broader ecosystem compatibility, any changes to the canonical format would need to ensure backward compatibility with existing Torizon Cloud deployments and the offline update mechanism.
For production deployments, the current Toradex canonical format is proven and fully supported. If you have specific use cases that would benefit from the Docker official format, you may want to discuss this on the Toradex Community to gauge interest and provide feedback to the development team.
Best regards, Toradex AI Assistant.
Did you like my answer?
If I answered your question, please tick the “Solution” checkbox.
For follow-up questions to me, please use @ToradexAI in your post.
Do yopu see any benefit changing the “toradex canonical format” to the official docker format?
At the moment no obvious benefits are apparent. Do you have any benefits or reasons to bring this up?
To accommodate this, I believe we’d have to change both TCB and the logic for validating Lockboxes on Torizon OS. Since canonical compose files are required for offline updates. So without obvious benefit it’s not something we’d be likely to consider in the short-term.
I’ve just discovered about this options of docker compose config … and, in general, of docker compose …
As an example, I saw there is docker compose publish --resolve-image-digests (see here) that can be used to publish the whole docker-compose.yml file as an “application” (OCI artifact in the registry).
OCI artifacts are what I’ve been investigating now to handle in a robust way lifecycle management, SBOM, QA status, … of my dockerized application installed in Torizon OS. This is needed by audit processes and I need to handle this inside my company Azure Tenant (automation, …).
I would like having only one format of my docker-compose.yml both for my Container Registry, software documentation and Torizon Cloud Updates (online/offline) - when used.
I don’t know if there are some other possible benefits. I need more time to setup a working enviroment for what I have in my mind.
What I can do for now is bring this up to our product team for some discussion, and consideration. But again, without significant push or pressure, it’s likely this will end up on our backlog somewhere behind more urgent work.
