Write cidfiles of Docker containers and mount them individually to /run/cid

[sairon]

There is no standard way to get the container ID in the container itself, which can be needed for instance for #6006. The usual pattern is to use the --cidfile argument of Docker CLI and mount the generated file to the container. However, this is feature of Docker CLI and we can't use it when creating the containers via API. To get container ID to implement native logging in e.g. Core as well, we need the help of the Supervisor.

This change implements similar feature fully in Supervisor's DockerAPI class that orchestrates lifetime of all containers managed by Supervisor. The files are created in the SUPERVISOR_DATA directory, as it needs to be persisted between reboots, just as the instances of Docker containers are.

Supervisor's cidfile must be created when starting the Supervisor itself, for that see home-assistant/operating-system#4276.

Proposed change

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality to the supervisor)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:
• Link to cli pull request:
• Link to client library pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Ruff (ruff format supervisor tests)
• Tests have been added to verify that the new code works.

If API endpoints or add-on configuration are added/changed:

• Documentation added/updated for developers.home-assistant.io
• CLI updated (if necessary)
• Client library updated (if necessary)

[mdegat01]

Neat, I like it. LGTM 👍

[agners]

It seems not intuitive, but key/bind target is the other way around, from docker-py docs:

The key is either the host path or a volume name, [...]

[sairon]

Huh, I had it the opposite way before and then changed it because I was somehow convinced should be like this but you're right 🤦 It'll need a few more changes.

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[sairon]

Fixed, there were a few more changes necessary because we need to distinguish between path in the Supervisor container when creating the files and path on the host for mounting. Tested to work correctly now:

# cat /mnt/data/supervisor/cid_files/hassio_dns.cid
488ff8754dbb4bb57bd3c5a22dd759cfbbbf631f1dcf6904701066477fc715a4
# docker exec -ti hassio_dns cat /run/cid
488ff8754dbb4bb57bd3c5a22dd759cfbbbf631f1dcf6904701066477fc715a4

[t3hk0d3]

IMO just a cidfile sounds too restrictive for me. Maybe more flexible mechanism similiar to k8s podinfo would be better idea?

Addons can get some use for other information, like HA Core version, addon version itself, installation date, etc. Overall having a single extendable file would be easier to maintain in the future than a number of different injected datasources.

[agners]

IMO just a cidfile sounds too restrictive for me. Maybe more flexible mechanism similiar to k8s podinfo would be better idea?

It resembles what is often done in vanilla Docker with --cidfile and a bind mount.

Addons can get some use for other information, like HA Core version, addon version itself, installation date, etc. Overall having a single extendable file would be easier to maintain in the future than a number of different injected datasources.

For add-ons we wire in /data/options.json today, which contains all the options.

Other information we usually fetch via the Supervisor API. The Supervisor API is not an option for this information for the Supervisor container itself (making something initial creation of the Supervisor script via the OS script in home-assistant/operating-system#4276). I guess we could use the Supervisor API approach for all the other containers which get started by the Supervisor, but fetching via Superviser API is more complex, and we usually want to do learn the container ID early in container starts to have logging setup. So this defends the current file approach.

Looking at the k8s podinfo implementation it seems that a complete directory gets bind mounted, with a couple of key/value files. I guess nothing would prevent us from wiring in more files. As for the cidfile, we could make it a key value thing too, but the simplicity of it and the fact that it aligns with what Docker offers via --cidfile has its advantage too 🤷 . Maybe as a compromise we could just prepare for additional files by bind mounting a folder instead of a single file 🤔 . E.g. /run/supervisor/, where today just the cidfile would reside.

[sairon]

As for the cidfile, we could make it a key value thing too, but the simplicity of it and the fact that it aligns with what Docker offers via --cidfile has its advantage too 🤷 .

Exactly, this provides simple way of exposing the container ID, which can be easily achieved using Docker CLI too. No special tooling is needed to get it in the container either and the simplicity makes testing or running in different environments easier as well.

Maybe as a compromise we could just prepare for additional files by bind mounting a folder instead of a single file 🤔 . E.g. /run/supervisor/, where today just the cidfile would reside.

The goal of this PR is to expose the container ID - which is a Docker runtime thing. Having other data in /run/supervisor would be coming from a different context, and we probably won't be able to provide the same data to Supervisor itself, so we'll be creating potential inconsistency in this concept. In the end, cost of bind-mounting the other data (which we don't know yet) to another place is negligible, and without a crystal ball this seems like unnecessary feature creep at this point.