add cgroup_namespace option to addon configuration

[eliottness]

Describe your core improvement

Add a cgroup_namespace option to apps config for the supervisor to pickup, mapping to Docker's cgroupns_mode parameter:

# addon config.yaml
cgroup_namespace: host

The Supervisor already exposes the other namespace options:

Option	Docker flag
host_network	--network=host
host_pid	--pid=host
host_ipc	--ipc=host
host_uts	--uts=host
cgroup_namespace	--cgroupns=host (proposed)

Frontend side this may require adapting the security rating of an app.

Values

Value	Behavior
(not set)	Docker daemon default (private on cgroup v2, host on cgroup v1)
host	Container shares the host's cgroup namespace
private	Container gets its own cgroup namespace (current default)

The Docker Python SDK already supports cgroupns_mode (API 1.41 / Docker CE 20.10)

Current limitations

On cgroup v2 hosts, Docker defaults to --cgroupns=private for containers. The Supervisor doesn't override this, so addon containers get their own cgroup namespace. This is fine for most addons, but it breaks one specific thing: BPF programs attached to cgroup hooks only affect processes inside the addon container, not host processes or other containers.

The kernel blocks setns() from a child cgroup namespace to a parent — by design, not a bug. So there's no workaround from inside a running container. The container has to be started with --cgroupns=host.

In Kubernetes, privileged pods get --cgroupns=host automatically via the container runtime. Docker doesn't do this, even with --privileged.

Use case

When building an addon that uses eBPF for network-level features. The BPF programs compile, load, and attach correctly inside the container. But because the container has a private cgroup namespace, the programs only intercept syscalls from processes inside the addon itself — not from other addons or the host.

I tried every workaround I could think of:

• nsenter --cgroup=/proc/1/ns/cgroup — Permission denied (kernel blocks child-to-parent setns)
• mount --bind /proc/1/root/sys/fs/cgroup — fails
• Pointing the BPF cgroup root at /proc/1/root/sys/fs/cgroup — attach still resolves to the container's cgroup

None of them work because the kernel enforces cgroup namespace isolation at the syscall level. The only fix is --cgroupns=host at container start time.

Technical benefits

This matters for addons that need to do system-level monitoring or networking. For example, any addon that attaches eBPF programs to cgroup hooks for traffic accounting, resource monitoring, or network interception will only see its own container's traffic — not the host's or other addons'. There have been community discussions about addons needing deeper system access, and the cgroup namespace is one of the remaining gaps.

Additional context

• Docker CLI --cgroupns PR
• Kubernetes hostCgroup feature request — same gap exists in K8s pod spec
• Cilium #15137 — BPF attached to wrong cgroup due to namespace isolation
• Compose spec #148 — Docker Compose also lacks this option
• HA Community: Ability to allow addons to mount system volumes — same need from a Datadog Agent addon

[mik-laj]

The technical case is solid, but I'm wondering about the practical fit for Home Assistant's target audience.

eBPF cgroup programs are a powerful tool, but writing and maintaining them is firmly in network/systems engineer territory - not something a typical home user would ever interact with, configure, or even be aware of. Home Assistant's strength is making complex home automation accessible; addons that require eBPF expertise to develop or debug feel more at home in an enterprise or datacenter context.
What's the realistic home user scenario here? Traffic accounting and network interception at the cgroup level sounds more like a feature for a corporate firewall appliance than a home automation hub.

[mik-laj]

Just to be transparent - I'm not a maintainer, just an occasional contributor, but from what I've seen, the project maintainers are pretty consistent about keeping HA focused on what it was built for: home automation and smart device management. Proposals that expand scope beyond that tend to get a cool reception regardless of technical merit.

OpenTelemetry has the same problem — it needs cgroup access for host metrics collection and can't get it from inside a private cgroup namespace.

Distributed tracing and metrics collection aren't relevant for home users. A typical HA setup talks to IoT devices that don't produce telemetry, and you wouldn't want to trust tracing data from external services anyway. This doesn't sound like a home automation use case.

Netdata already hacks around this with nsenter + docker restart.

HA already ships add-on monitoring built in. What specifically is missing there?

Datadog Agent flat out can't work without it.

Running Datadog as a standalone container outside the addon system is actually the more correct approach - it lets the agent monitor the host and HA itself, including cases where the Supervisor fails to start. Packaging a monitoring tool that depends on the Supervisor to run is the wrong model. This is already possible if you have root access on HAOS.

These aren't power-user edge cases, they're popular monitoring tools that addon developers want to package.

Popular among cloud and container engineers - not among home users.

[eliottness]

Thanks for your insights @mik-laj I won't deny that I am a cloud engineer myself. I think this feature will become necessary for home users soon enough, but that is my personal opinion so it does not count, you are right on all accounts.

My second point still stands I think, especially considering this is low amount of work.

[mik-laj]

Thanks for the kind response, and fair enough on the second point - the implementation itself probably isn't the hard part. But "low amount of work" usually refers to the initial commit, not the full lifecycle cost:

• Documentation - someone has to write it and keep it up to date
• Release management - someone has to make sure the change is properly packaged and shipped
• Bug fixes - if something breaks, someone has to fix it
• Testing - someone has to write and maintain tests
• Community support - questions will come up about how to use it, and ideally someone answers them
• Cognitive overhead - even a small, rarely used option has to be understood by anyone making changes in that area of the codebase

There's also a broader risk: adding this option expands the effective audience for the addon system beyond smart home users to cloud and infrastructure engineers. That's likely to increase support volume and attract further feature requests in the same direction. Better to draw that line early.

No single option like this will kill the project. But if the bar for adding something is "one person needs it and the initial implementation is small", these costs accumulate. The maintenance burden of the codebase is the sum of every small decision like this one.

And stepping back - we still don't have a concrete use case where a home user benefits from this. The examples given are all tools for people running infrastructure, and those people already have workable alternatives.

[eliottness]

Appreciate the thoughtful engagement but I don't think a product engineering course is necessary to describe your point considering all of this apply to any feature, this is still low amount of work comparing to other features. In fact I came here in the first place because I saw plethora of hacks to get this last bout of admin permissions for addons in the community. The one where the addon gives itself the permission via docker_api: true from inside the container and restart itself with this new flag was the most creative one but it does not work anymore sadly.

Again, as a home user using HA green myself because of the stability benefits, and since running HA supervisor outside of HAOS is no longer an option. I need complete control over my machine which I don't have right now because the loop is not closed. Overall cgroups are not only about eBPF they are about control over cpu, memory and io limits of all kinds.

[eliottness]

The missing flag has real consequences right now, in the official store. hassio-addons/addon-glances — maintained by the HA team — needs --cgroupns=host for accurate container metrics on cgroup v2. Since the Supervisor can't provide it, the addon uses host_pid: true instead, which breaks S6-Overlay. Their own run.sh documents this directly:

"The Glances add-on runs in the host PID namespace, therefore it cannot use the regular S6-Overlay; hence this add-on uses a 'old school' script to run; with a couple of 'hacks' to make it work."

The result: users get wrong memory numbers (addon #594), matching a known upstream Glances issue whose fix is — --cgroupns=host.

It's not just Glances. Netdata does nsenter --target 1 --mount + docker restart to splice host cgroup paths manually. Prometheus Node Exporter, Grafana Alloy, and Telegraf all reach for host_pid: true or full_access + SYS_ADMIN as blunt workarounds. These are easy access monitoring tools, not datacenter software.

With HAOS growing as a general home server OS, some of us run our whole home infrastructure through it — media, network, automation. Saying that's out of scope means pushing addon developers toward hacks that are harder to maintain and produce worse results than just exposing the flag would.

[tomwilkie]

👋 hi there - thank you @eliottness for filling this feature request; I was the one who raised this on the forum ~a year ago: https://community.home-assistant.io/t/mount-hosts-proc-sys-into-add-on-container/848705

To give some concrete reasons why I'd like better observability of my haos instance:

• I was using music assistant and having random drops. Having the debug logs and CPU data in a single place allowed me to quickly figure out his was a cpu starvation issue
• I've had a really unstable zigbee mesh, and adding metrics to it has allowed me to narrow it down to specific devices causing issues; removing them made the mesh much more stable

I am super biased here - I work on Grafana, Prometheus etc - but I feel like having better support for observability & telemetry would make is easier to debug issues with home assistant.