Skip to content
SHC Docs

May builtin/traefik and builtin/keycloak drop securityopt? (2026-08-11)

Superseded by New-line runtime. The text below is the record as of its date.

Status: RULED 2026-09-25. Keep the guard, fix the built-ins, change nothing on compose. None of A, B or C as written. The swarm render leaves the key out and every other runtime keeps it: addons/keycloak and addons/traefik wrap security_opt in {% if shc.runtime != "swarm" %}, where shc.runtime is the same EffectiveRuntime(opts.Runtime) the swarm loader gate decides on (ce shcTemplateNamespace). Swarm runs what it always ran, since it dropped the key anyway. Compose keeps the waiver. addons/postgres got the same treatment for the server’s restart: unless-stopped, which conflicted with its swarm-only restart_policy: {condition: none}. The floor below does not move: the catalogue sweep neutralises Jinja by keeping the first branch, so it still counts both built-ins as carriers (re-measured at ruling time: ten packages, floor nine).

Two consequences of the ruling, recorded here because nothing else says them:

  • keycloak’s tmpfs is runtime-split too. The long form listed under “What is already done” below mounts the same thing but changes the compose container config, so it would have recreated every live Keycloak on its next update. Compose keeps tmpfs: [/tmp]; the long-form volume is emitted only on swarm. The shc store’s TestAddonComposeRenderMatchesTheGolden compares the whole non-swarm render of every built-in against goldens rendered from main (ce modules/app/testdata/addon-compose-renders), so a change like that fails by name.
  • A swarm restore of a built-in from an archive older than this ruling is refused. Recover renders the archived app tree, which still carries security_opt unconditionally, and the swarm loader gate refuses it with X400073SWMXLT before anything is written. Accepted: the built-ins are the compose-runtime system stacks on both estates (not re-checked on the live engines at ruling time), so no such archive should exist, and the refusal names the key and the way out (--runtime compose). Before the guard the same restore deployed green without the exemption. Option C stays open as the way to actually give swarm traefik and keycloak the exemption.

Status: OPEN. Owner ruling required. It blocks a landing.

Decision. builtin/traefik and builtin/keycloak each declare security_opt: [apparmor:unconfined]. docker stack deploy loads that key, prints it back, and never converts it, so on a swarm-runtime estate the exemption is silently absent. ce’s swarm guard now refuses rather than deploy green-and-wrong, and that refusal is what stops both system built-ins from being installable on swarm at all. Three ways out; all three change something the owner owns. Ruling wanted on which.

Cost of delay: blocks-work: lane/20260811-swarm-silent-discards is the last of nineteen lanes not landed, and this is the only thing still holding it (everything else in that lane is fixed on fix/swarm-discards-deadlock, ce). It is also latent-security: nothing is wrong on any estate today, because every live deployment runs --runtime compose.


What is actually true (measured, not read off docs)

Section titled “What is actually true (measured, not read off docs)”

1. docker stack deploy drops the key in silence, and the preflight cannot see it. docker stack config returns exit 0, echoes security_opt back verbatim, and writes zero bytes to stderr, because stack config never calls loadComposeFile, which is where the “Ignoring unsupported options” warning lives (docker/cli cli/command/stack/loader.go:42-45 vs cli/command/stack/config.go). So the existing stack-config preflight (X500062SWMCFG) is structurally blind to this whole class; more preflight would not have found it.

2. The compose→swarm converter genuinely never reads it. security_opt is in docker’s own composetypes.UnsupportedProperties (cli/compose/types/types.go:17-34, sixteen entries at v29.4.1), and nothing in cli/compose/convert/ reads service.SecurityOpt. Two independent derivations, field-usage over ServiceConfig, and docker’s own declaration, agree.

3. ★ BUT SWARM ITSELF CAN EXPRESS IT. This corrects the framing the lane was filed under (“swarm has NO security_opt equivalent at all, so there is no translation”). That is true of docker stack deploy; it is not true of swarm. swarm.ContainerSpec.Privileges carries both:

type Privileges struct {
CredentialSpec *CredentialSpec
SELinuxContext *SELinuxContext
Seccomp *SeccompOpts `json:",omitempty"`
AppArmor *AppArmorOpts `json:",omitempty"`
NoNewPrivileges bool
}
const (
AppArmorModeDefault AppArmorMode = "default"
AppArmorModeDisabled AppArmorMode = "disabled"
)

(github.com/docker/[email protected] api/types/swarm/container.go:44-84.) AppArmorMode: "disabled" is the swarm spelling of apparmor:unconfined. Custom AppArmor profiles are not supported, but neither built-in wants one; both want the profile off.

What is missing is only the WIRE-UP: docker stack deploy will not put it there, and docker service create --help at 29.4.1 offers no --security-opt, --apparmor or --seccomp flag. The field is reachable only from the daemon API.

4. Both exemptions are load-bearing, and they are load-bearing for different reasons.

  • builtin/traefik/compose.yaml:499-501: “Traefik needs unrestricted apparmor for Docker socket access and dynamic config reloads”. It mounts /var/run/docker.sock:/var/run/docker.sock:ro (:590). Dropped, the task runs under docker’s default apparmor profile and the failure surfaces as an unexplained permission denial on the socket, i.e. ingress comes up and does not work.
  • builtin/keycloak/compose.yaml:39-41: “Keycloak JVM uses native memory access (Quarkus/Netty direct buffers)”. Dropped, the failure is a JVM native-memory error at some later point, i.e. SSO comes up and does not work.

5. This host has AppArmor enabled (/sys/module/apparmor/parameters/enabled → Y), so the key is not inert here. On a host with no AppArmor LSM the key is a no-op and dropping it costs nothing; which estates are which is not something this write-up measured, and it is worth one command per estate before ruling (docker info | grep -i apparmor).

6. Removing the key changes Compose-runtime behaviour on every existing estate. 24 deployments run on the compose runtime across two estates. compose reads security_opt; swarm is what ignores it. So “drop it for swarm’s benefit” is not a swarm-only edit; it re-confines traefik and keycloak on every live compose deployment, today.


Why this reached the owner rather than being decided in the lane

Section titled “Why this reached the owner rather than being decided in the lane”

The guard is not the problem, and neither is the built-in. Two landed guards state opposite post-conditions about the same two files:

  • TestBuiltinsCarryNoUntranslatableSwarmConstruct (ce d04fb18): every rendered built-in must carry NOTHING docker stack deploy discards. Its stake: “a built-in that swarm cannot load is a swarm estate with no ingress, no system store, or both.”
  • the silent-discard guard: security_opt is discarded, so it must be refused.

Cleaning the built-ins satisfies the first and (before this branch) broke the second; leaving them satisfies the second and breaks the first. Every exit that does not involve a ruling is a weakening of one of the two, and weakening either reintroduces exactly the defect it was written to catch. The other three collisions in that deadlock were mechanical and are fixed on fix/swarm-discards-deadlock (see “What is already done”, below). This one is not mechanical: it is a question about what the platform supports.


A. Rule that swarm-loadable wins: delete security_opt from both built-ins

Section titled “A. Rule that swarm-loadable wins: delete security_opt from both built-ins”

What it costs. Traefik loses unrestricted apparmor on compose too, on all 24 live deployments, against a mounted Docker socket. Keycloak’s Quarkus JVM loses it for native memory access. Both regressions are runtime and silent until exercised, exactly the class this whole seam exists to stop shipping. Neither is currently measured: nobody has run either image under docker’s default apparmor profile on these estates.

What it buys. Both guards go green, the lane lands, no new code.

Verdict: not recommended without measurement. This trades a latent swarm defect for a live compose regression, on the ingress and the SSO, to unblock a runtime no estate is on yet. If it is taken, it must be taken after running both images unconfined-free on a scratch estate, not before.

B. Rule that the refusal stands: keep security_opt, accept that the two system built-ins are compose-only

Section titled “B. Rule that the refusal stands: keep security_opt, accept that the two system built-ins are compose-only”

What it costs. A swarm-runtime estate cannot install its own ingress or its own SSO. That is the exact sentence TestBuiltinsCarryNoUntranslatableSwarmConstruct exists to prevent, so that guard has to be told about the exception explicitly (an allow-list of “these two services may carry security_opt, and here is the ruling that says so”), or it stays red forever.

★ An allow-list is a weakening of a fitness rule, and it is only honest if it is (a) keyed to these two services by name, (b) carrying the ruling’s identifier in the failure text, and (c) accompanied by the refusal still firing at install time so an operator attempting --runtime swarm is told why, not merely allowed to proceed into a broken estate. Written any looser, it is the “allowlist a test to reach green” move this repository bans.

What it buys. No behaviour change anywhere. Honest about the limitation. Swarm support for the two system packages is deferred, not faked.

C. ★ Wire the property swarm actually has: post-deploy ServiceUpdate setting Privileges.AppArmor.Mode: disabled

Section titled “C. ★ Wire the property swarm actually has: post-deploy ServiceUpdate setting Privileges.AppArmor.Mode: disabled”

The finding in (3) makes this a real option rather than a wish. docker stack deploy cannot set it and docker service create has no flag, but the daemon API field exists and means precisely what apparmor:unconfined means. SHC already drives the daemon directly elsewhere.

What it costs. New code on the swarm install path, and a genuinely awkward ordering problem: the stack deploys with the default profile and is patched immediately after, so there is a window in which traefik is running confined against the socket. Whether that window is acceptable (traefik would fail its socket reads and retry) needs measuring. It is also the only option that adds a maintenance surface, a second way of expressing a security exemption, which must not drift from the compose one.

What it buys. The guarantee is kept on both runtimes rather than dropped on one or refused on both. It is the only option under which a swarm estate gets a working ingress AND a working SSO AND no compose regression.

Verdict: recommended to cost, at least. If the ServiceUpdate window is tolerable, C is strictly better than A and B. If it is not, the fallback is B, because B defers a capability and A regresses a live one.


On ce branch fix/swarm-discards-deadlock (which merges lane/20260811-swarm-silent-discards):

  • Restart-equivalence carve-out. restart: beside a deploy.restart_policy is only reported when the two keys say different things. no↔none, always↔any and on-failure↔on-failure (bounds compared) are forgiven; unless-stopped and every mismatch still fire. This was detector over-fire: traefik-init and postgres-guard declare both keys deliberately, and the ordering lane documented them as equivalent. Measured through docker’s own converter.
  • keycloak’s tmpfs moved from tmpfs: [/tmp] to volumes: [{type: tmpfs, target: /tmp}]. Docker’s converter produces mounts=[] for the first and mounts=[{"Type":"tmpfs","Target":"/tmp"}] for the second; under compose both produce a byte-identical writable tmpfs mount. One offence removed, no behaviour change.
  • The corpus guard’s by-name teeth re-sourced from a committed fixture (modules/app/testdata/swarm-discards/) instead of from the live built-ins, so the detector is proven without holding the real tree hostage. Empty-corpus and deny-list-completeness tripwires kept and strengthened.

Still red, and only this: service keycloak: security_opt: and service traefik: security_opt:, on scenarios 0-2 of each, in TestBuiltinsCarryNoUntranslatableSwarmConstruct and TestBuiltinsSurviveTheSwarmInstallPipeline. Nothing else.

One thing the ruling must carry with it if it is A or C: TestCatalogueSecurityOptCarriersAreRefusedUnderSwarm’s securityOptPackageFloor = 9 is a measurement of the assembled catalogue, and two of the nine are these built-ins. It has to be re-measured in the same change, not lowered ahead of the ruling.