Skip to content

Commit 3961b7d

Browse files
authored
docs: curate 0.4.0 release notes (#80)
1 parent 8bf1d0f commit 3961b7d

1 file changed

Lines changed: 68 additions & 0 deletions

File tree

‎planning/releases/0.4.0.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
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

Comments
 (0)