|
| 1 | +# compose2pod 0.4.0 — Podman 5.x support: the script owns `/etc/hosts` |
| 2 | + |
| 3 | +Generated scripts now own `/etc/hosts` outright instead of asking Podman to |
| 4 | +populate it with pod-level `--add-host`. Every container runs under `--no-hosts` |
| 5 | +and bind-mounts a hosts file compose2pod writes at run time. Because Podman no |
| 6 | +longer manages the file, the pre-6.0.0 bug that wiped it can no longer fire — |
| 7 | +pod-internal name resolution is now correct on **every** Podman version, |
| 8 | +including the 5.x line that has no fix for that bug. The `Podman >= 6.0.0` |
| 9 | +requirement is gone. |
| 10 | + |
| 11 | +## Why |
| 12 | + |
| 13 | +Before 6.0.0, a container stopping inside a multi-container pod made Podman |
| 14 | +regenerate the pod's shared `/etc/hosts` and delete every entry — wiping the |
| 15 | +`--add-host` set that was the pod's only source of name resolution. A |
| 16 | +`service_completed_successfully` dependency (a migration that runs and exits) |
| 17 | +triggered it, producing a `could not translate host name` failure deep inside an |
| 18 | +unrelated service, minutes after the script appeared to succeed. |
| 19 | + |
| 20 | +The fix ([containers/podman#28494](https://github.com/containers/podman/pull/28494)) |
| 21 | +first shipped in Podman 6.0.0 and was **never backported to any 5.x** — verified |
| 22 | +against the `v5.8` release notes and tag containment for 5.8.0–5.8.5. Anyone |
| 23 | +pinned to a Fedora-based Podman 5.x image could not get a fixed Podman, and the |
| 24 | +0.3.0 run-time version guard could only *warn*, not fix. This release removes the |
| 25 | +cause instead of warning about it. |
| 26 | + |
| 27 | +## Change |
| 28 | + |
| 29 | +- **The script owns `/etc/hosts`.** `podman pod create` and every `podman run` |
| 30 | + now carry `--no-hosts`; no `--add-host` is emitted. The script writes a full |
| 31 | + hosts file to a `mktemp` path — `127.0.0.1 localhost`, `::1 localhost`, each |
| 32 | + service alias/hostname → `127.0.0.1`, each `extra_hosts` host → its address — |
| 33 | + and bind-mounts it read-only into every container as |
| 34 | + `-v "$hostsfile":/etc/hosts:ro,z`, removing it on teardown. The `z` relabel is |
| 35 | + mandatory on SELinux-enforcing hosts (Fedora) and a no-op elsewhere. |
| 36 | +- **Works on any Podman.** With `--no-hosts`, Podman never rewrites the file, so |
| 37 | + the stop-wipe cannot occur regardless of version. Behavior is identical on 5.x |
| 38 | + and 6.x. |
| 39 | +- **The Podman-version guard is removed.** The run-time warning 0.3.0 added |
| 40 | + existed only to flag the now-impossible bug, so it is deleted along with the |
| 41 | + documented version floor. |
| 42 | + |
| 43 | +## Downstream |
| 44 | + |
| 45 | +- **No pre-editing needed on Podman 5.x.** Compose files with a run-to-completion |
| 46 | + dependency that previously lost name resolution now work unchanged. |
| 47 | +- **`host.containers.internal` / `host.docker.internal` are no longer provided.** |
| 48 | + Under `--no-hosts`, compose2pod cannot resolve Podman's gateway IP to synthesize |
| 49 | + them (Docker Compose on Linux does not add them by default either). A service |
| 50 | + that needs to reach the host adds an explicit `extra_hosts` entry with the |
| 51 | + address it wants. |
| 52 | +- **Everything else is unchanged.** The alias/hostname resolution set, the |
| 53 | + `extra_hosts` merge, and the conflict rule (a name landing on two addresses is |
| 54 | + refused) behave exactly as before — only the mechanism that carries them to the |
| 55 | + container changed. |
| 56 | + |
| 57 | +## Internals |
| 58 | + |
| 59 | +- Tests at 100% line coverage (enforced); `ruff select=ALL`, `ty`, `eof-fixer` |
| 60 | + clean; the conformance harness (real Docker CLI) and integration harness (real |
| 61 | + Podman) both green — the integration suite exercises name resolution surviving a |
| 62 | + completion container's stop. |
| 63 | +- The mechanism was validated end-to-end in a Fedora CoreOS VM before it was |
| 64 | + written: with `--no-hosts` and the bind-mounted file, a container's stop leaves |
| 65 | + the hosts file byte-identical, and the missing `:z` relabel was caught there |
| 66 | + (an un-relabeled mount is unreadable inside the container). See |
| 67 | + `planning/changes/2026-07-20.01-own-etc-hosts-via-no-hosts.md` for the full |
| 68 | + rationale, the upstream research, and the rejected alternatives. |
0 commit comments