fix: emit add-host at podman pod create instead of podman run

Current podman rejects --add-host on a container joining a pod
("network cannot be configured when it is shared with a pod").
Moves alias/hostname add-host emission from run_flags to
pod_create_flags, alongside dns/sysctls, and folds extra_hosts in as
a pod-level key merged into the same add-host set (conflict refused
rather than guessed at).

Author: lesnik512

architecture/supported-subset.md

@@ -67,9 +67,11 @@ warns (ignored, behavior-neutral inside a single pod) or raises
 - **`annotations`:** list or mapping, emitted as repeated `--annotation`
   (`KEY=value`, or bare `KEY` for a null value), sharing the `_MAP_FLAGS`
   machinery with `labels`.
-- **`extra_hosts`:** list (`- host:ip`) or mapping (`host: ip`), emitted as
-  per-service `--add-host host:ip`. Distinct from the alias/hostname entries
-  (which resolve to `127.0.0.1`); IPv6 values keep their colons.
+- **`extra_hosts`:** list (`- host:ip`) or mapping (`host: ip`), pod-level like
+  `dns`/`sysctls` — see the Pod-level options section below. Distinct from
+  the alias/hostname set in one respect: alias/hostname resolution is
+  always fixed at `127.0.0.1`, while `extra_hosts` carries a user-specified
+  address; IPv6 values keep their colons.
 - **`pull_policy`:** a validated enum mapped to podman's `--pull`
   (`if_not_present` → `missing`; `always`/`never`/`missing` pass through),
   emitted literally. `build` and unknown values are rejected — compose2pod
@@ -181,36 +183,48 @@ it, so a handful of Compose keys cannot be per-container `podman run` flags.
 compose2pod hoists them onto `podman pod create` instead
 (`compose2pod/pod.py`) — the tool's only pod-create flags.
 
-- **Supported:** `dns`, `dns_search`, `dns_opt`, `sysctls` — mapped to
-  `--dns`, `--dns-search`, `--dns-option`, `--sysctl` respectively (`_DNS_KEYS`,
+- **Supported:** `dns`, `dns_search`, `dns_opt`, `sysctls`, `extra_hosts` —
+  mapped to `--dns`, `--dns-search`, `--dns-option`, `--sysctl`, and (merged
+  with the alias/hostname set) `--add-host` respectively (`_DNS_KEYS`,
   `pod.py`).
-- **Aggregation is closure-scoped:** `pod_create_flags(services, order)` is
-  called with `order` — the target's dependency closure (`startup_order`) —
-  exactly like other closure-scoped constructs (secrets, configs). `dns` /
-  `dns_search` / `dns_opt` are unioned across the closure (deduplicated,
-  first-seen order); `sysctls` are unioned by key, and two services in the
-  closure setting the same key to different values is refused
-  (`UnsupportedComposeError: conflicting sysctl ...`) rather than resolved by
-  last-writer-wins.
+- **Aggregation is closure-scoped:** `pod_create_flags(services, order,
+  hosts)` is called with `order` — the target's dependency closure
+  (`startup_order`) — exactly like other closure-scoped constructs (secrets,
+  configs). `dns` / `dns_search` / `dns_opt` are unioned across the closure
+  (deduplicated, first-seen order); `sysctls` are unioned by key, and two
+  services in the closure setting the same key to different values is
+  refused (`UnsupportedComposeError: conflicting sysctl ...`) rather than
+  resolved by last-writer-wins. `--add-host` is seeded from the
+  alias/hostname set (`hosts`, computed document-wide by `graph.hostnames`,
+  not closure-scoped — pre-existing, orthogonal behavior), then layered with
+  each closure service's `extra_hosts` (closure-scoped like `dns`/`sysctls`);
+  a host name landing on two different addresses — across two services'
+  `extra_hosts`, or between an `extra_hosts` entry and an alias's fixed
+  `127.0.0.1` — is refused (`UnsupportedComposeError: conflicting host ...`),
+  the same refuse-rather-than-guess rule as the `sysctls` conflict.
 - **Value shapes:** `dns` / `dns_search` / `dns_opt` accept a string or a list
   of strings; `sysctls` accepts a mapping (`key: value`) or a list of
   `"key=value"` strings, each value a string or number. A `${VAR}` inside a
   value is wrapped in `_Expand` like other interpolated fields, so it stays
   live at run time and counts toward `referenced_variables` — the generated
   script's own shell expands it when it runs, not compose2pod at generation
-  time.
+  time. `--add-host` entries render differently by source: an alias/hostname
+  entry stays a plain unquoted token (pre-existing behavior, unchanged by
+  this move), while an `extra_hosts` entry goes through `_Expand` (quoted,
+  `${VAR}`-live) — same as before it was per-service.
 - **Pod-wide divergence:** unlike every other service key, these apply to
   every container in the pod once emitted — including services that never
-  declared them — because the pod shares one `/etc/resolv.conf` and one
-  sysctl set. `validate()` (`compose2pod/parsing.py`) is target-agnostic
-  shape validation over the whole document: whenever any service anywhere
-  declares `dns` / `dns_search` / `dns_opt` / `sysctls` (`uses_pod_options`),
-  it emits the warning "dns/sysctls apply pod-wide -- all containers in the
-  pod share one /etc/resolv.conf and sysctl set", regardless of whether that
+  declared them — because the pod shares one `/etc/resolv.conf`, one sysctl
+  set, and one `/etc/hosts`. `validate()` (`compose2pod/parsing.py`) is
+  target-agnostic shape validation over the whole document: whenever any
+  service anywhere declares `dns` / `dns_search` / `dns_opt` / `sysctls` /
+  `extra_hosts` (`uses_pod_options`), it emits the warning "dns/sysctls/
+  extra_hosts apply pod-wide -- all containers in the pod share one
+  /etc/resolv.conf, sysctl set, and /etc/hosts", regardless of whether that
   service turns out to be inside the target's closure. Conversely, at emit
-  time a `dns` / `sysctls` declaration on a service outside the target's
-  closure is silently ignored by `pod_create_flags` — no flag is emitted for
-  it, since that service is never run.
+  time a `dns` / `sysctls` / `extra_hosts` declaration on a service outside
+  the target's closure is silently ignored by `pod_create_flags` — no flag
+  is emitted for it, since that service is never run.
 - **Non-goals:** per-service DNS/sysctls — impossible inside a
   shared-namespace pod, not a compose2pod limitation; last-writer-wins on a
   sysctl key conflict — refused instead, matching the refuse-on-conflict

compose2pod/emit.py

@@ -93,11 +93,9 @@ def _add_volume_flags(flags: list[Token], svc: dict[str, Any], project_dir: str)
         flags += ["--tmpfs", _Expand(value=mount)]
 
 
-def run_flags(name: str, svc: dict[str, Any], pod: str, hosts: list[str], project_dir: str) -> list[Token]:
+def run_flags(name: str, svc: dict[str, Any], pod: str, project_dir: str) -> list[Token]:
     """Flag tokens (unquoted) for `podman run` of one service."""
     flags: list[Token] = ["--pod", pod, "--name", f"{pod}-{name}"]
-    for host in hosts:
-        flags += ["--add-host", f"{host}:127.0.0.1"]
     _add_env_flags(flags, svc, project_dir)
     _add_volume_flags(flags, svc, project_dir)
     _add_health_flags(flags, svc.get("healthcheck") or {})
@@ -168,9 +166,9 @@ def _collect_vars(tokens: list[Token], names: set[str]) -> None:
             names.update(variable_names(token.value))
 
 
-def _run_tokens(name: str, services: dict[str, Any], options: EmitOptions, hosts: list[str]) -> list[Token]:
+def _run_tokens(name: str, services: dict[str, Any], options: EmitOptions) -> list[Token]:
     svc = services[name]
-    tokens = run_flags(name, svc, options.pod, hosts, options.project_dir)
+    tokens = run_flags(name, svc, options.pod, options.project_dir)
     entrypoint = entrypoint_tokens(svc)
     if entrypoint:
         tokens += ["--entrypoint", entrypoint[0]]
@@ -230,7 +228,7 @@ def _plan(compose: dict[str, Any], options: EmitOptions) -> PlannedScript:
     if store_teardown:
         teardown += f"; {store_teardown}"
     lines.append(f"trap '{teardown}' EXIT")
-    pod_flags = pod_create_flags(services, order)
+    pod_flags = pod_create_flags(services, order, hosts)
     _collect_vars(pod_flags, names)
     pod_create = f"podman pod create --name {shlex.quote(options.pod)}"
     if pod_flags:
@@ -246,7 +244,7 @@ def _plan(compose: dict[str, Any], options: EmitOptions) -> PlannedScript:
                 attempts = max(HEALTHY_WAIT_BUDGET_SECONDS // interval, 1)
                 lines.append(f"wait_healthy {shlex.quote(f'{options.pod}-{dep}')} {attempts} {interval}")
                 waited.add(dep)
-        run_tokens = _run_tokens(name, services, options, hosts)
+        run_tokens = _run_tokens(name, services, options)
         _collect_vars(run_tokens, names)
         if name == options.target:
             _emit_target(lines, run_tokens, options)

compose2pod/keys.py

@@ -126,13 +126,6 @@ def _extra_host_pairs(value: list[Any] | dict[str, Any]) -> list[Any]:
     return [f"{host}:{ip}" for host, ip in value.items()]
 
 
-def _emit_extra_hosts(value: Any) -> list[Token]:  # noqa: ANN401 - Compose values are untyped YAML/JSON
-    tokens: list[Token] = []
-    for entry in _extra_host_pairs(value):
-        tokens += ["--add-host", _Expand(value=str(entry))]
-    return tokens
-
-
 def _validate_pull_policy(name: str, key: str, value: Any) -> None:  # noqa: ANN401 - Compose values are untyped
     if value is not None and (not isinstance(value, str) or value not in PULL_POLICY_MAP):
         allowed = "/".join(PULL_POLICY_MAP)
@@ -194,7 +187,6 @@ def _emit_ulimits(value: Any) -> list[Token]:  # noqa: ANN401 - Compose values a
     "devices": _list("--device"),
     "labels": _map("--label"),
     "annotations": _map("--annotation"),
-    "extra_hosts": KeySpec(validate=_validate_map, emit=_emit_extra_hosts),
     "pull_policy": KeySpec(validate=_validate_pull_policy, emit=_emit_pull_policy),
     "ulimits": KeySpec(validate=_validate_ulimits, emit=_emit_ulimits),
     "mem_limit": _number_scalar("--memory"),
@@ -233,4 +225,5 @@ def _emit_ulimits(value: Any) -> list[Token]:  # noqa: ANN401 - Compose values a
     "dns_search",
     "dns_opt",
     "sysctls",
+    "extra_hosts",
 }

compose2pod/parsing.py

@@ -137,6 +137,7 @@ def validate(compose: dict[str, Any]) -> list[str]:
     stores.validate(compose)
     if uses_pod_options(services):
         warnings.append(
-            "dns/sysctls apply pod-wide -- all containers in the pod share one /etc/resolv.conf and sysctl set"
+            "dns/sysctls/extra_hosts apply pod-wide -- all containers in the pod share one "
+            "/etc/resolv.conf, sysctl set, and /etc/hosts"
         )
     return warnings

compose2pod/pod.py

@@ -3,11 +3,11 @@
 from typing import Any
 
 from compose2pod.exceptions import UnsupportedComposeError
-from compose2pod.keys import Token, _Expand
+from compose2pod.keys import Token, _Expand, _extra_host_pairs, _validate_map
 
 
 _DNS_KEYS = {"dns": "--dns", "dns_search": "--dns-search", "dns_opt": "--dns-option"}
-_POD_OPTION_KEYS = (*_DNS_KEYS, "sysctls")
+_POD_OPTION_KEYS = (*_DNS_KEYS, "sysctls", "extra_hosts")
 
 
 def _as_str_list(name: str, key: str, value: Any) -> list[str]:  # noqa: ANN401 - Compose values are untyped
@@ -47,6 +47,8 @@ def validate_pod_options(name: str, svc: dict[str, Any]) -> None:
             _as_str_list(name, key, svc[key])
     if "sysctls" in svc:
         _sysctl_pairs(name, svc["sysctls"])
+    if "extra_hosts" in svc:
+        _validate_map(name, "extra_hosts", svc["extra_hosts"])
 
 
 def uses_pod_options(services: dict[str, Any]) -> bool:
@@ -85,10 +87,42 @@ def _sysctl_flags(services: dict[str, Any], order: list[str]) -> list[Token]:
     return tokens
 
 
-def pod_create_flags(services: dict[str, Any], order: list[str]) -> list[Token]:
-    """Pod-create flag tokens aggregated across the closure `order`.
+def _add_host_flags(services: dict[str, Any], order: list[str], hosts: list[str]) -> list[Token]:
+    """Merge alias/hostname hosts (fixed 127.0.0.1) with extra_hosts (order-scoped) into one add-host set.
 
-    dns/dns_search/dns_opt are unioned (dedup, first-seen order); sysctls are
-    unioned by key and a same-key value conflict is refused.
+    A host name landing on two different addresses -- across services' extra_hosts,
+    or against an alias's fixed 127.0.0.1 -- is refused rather than guessed at, matching
+    the sysctls conflict rule below. Alias entries render as plain tokens (unquoted, as
+    before this move); extra_hosts entries render via `_Expand` (as before, quoted/interpolated)
+    -- relocating the flags changes nothing else observable about either source.
     """
-    return _dns_flags(services, order) + _sysctl_flags(services, order)
+    merged: dict[str, str] = {}
+    from_extra_hosts: set[str] = set()
+    for host in hosts:
+        merged[host] = "127.0.0.1"
+    for name in order:
+        svc = services[name]
+        if "extra_hosts" not in svc:
+            continue
+        for entry in _extra_host_pairs(svc["extra_hosts"]):
+            host, _sep, addr = str(entry).partition(":")
+            if merged.get(host, addr) != addr:
+                msg = f"service {name!r}: conflicting host {host!r} ({merged[host]!r} vs {addr!r})"
+                raise UnsupportedComposeError(msg)
+            merged[host] = addr
+            from_extra_hosts.add(host)
+    tokens: list[Token] = []
+    for host, addr in merged.items():
+        value = _Expand(value=f"{host}:{addr}") if host in from_extra_hosts else f"{host}:{addr}"
+        tokens += ["--add-host", value]
+    return tokens
+
+
+def pod_create_flags(services: dict[str, Any], order: list[str], hosts: list[str]) -> list[Token]:
+    """Pod-create flag tokens aggregated across the closure `order`, plus `hosts` for add-host.
+
+    Add-host is merged from alias/hostname resolution (`hosts`, fixed 127.0.0.1) and each
+    closure service's `extra_hosts`, conflict-checked (see `_add_host_flags`). dns/dns_search/
+    dns_opt are unioned (dedup, first-seen order); sysctls are unioned by key.
+    """
+    return _add_host_flags(services, order, hosts) + _dns_flags(services, order) + _sysctl_flags(services, order)

planning/changes/2026-07-13.01-pod-level-add-host.md

@@ -0,0 +1,113 @@
+---
+summary: Move all `--add-host` emission (alias/hostname resolution and `extra_hosts`) from per-service `podman run` to `podman pod create`, since current podman rejects network config on a container joining a pod; `extra_hosts` becomes pod-wide like `dns`/`sysctls`, with a same-host-different-address conflict (against another service's `extra_hosts` or an alias's fixed `127.0.0.1`) refused rather than guessed at.
+---
+
+# Design: pod-level `--add-host`
+
+## Summary
+
+Current podman rejects `--add-host` on `podman run` for a container joining a
+pod (`invalid config provided: extra host entries must be specified on the
+pod: network cannot be configured when it is shared with a pod`), discovered
+by the new integration harness (`planning/changes/2026-07-12.04-integration-harness.md`)
+on its first real CI run. Every generated script with more than a trivial
+single-service pod currently fails at run time. The fix hoists all
+`--add-host` emission onto `podman pod create`, alongside `dns`/`sysctls`
+(`compose2pod/pod.py`). This forces `extra_hosts` — previously genuinely
+per-service — to become pod-wide like `dns`/`sysctls` already are; a same-host
+conflict is refused rather than resolved by guessing.
+
+## Motivation
+
+`run_flags` (`compose2pod/emit.py:96-100`) emits `--add-host <name>:127.0.0.1`
+for every alias/hostname/container_name in the whole document, on every
+service's `podman run` line — and `extra_hosts` (`compose2pod/keys.py:197`)
+emits a per-service `--add-host host:ip` the same way. Both are now rejected
+outright by podman once a container joins a pod. The integration harness's
+first CI run (PR #41) demonstrated this on all three seed scenarios:
+`Error: invalid config provided: extra host entries must be specified on the
+pod: network cannot be configured when it is shared with a pod`.
+
+## Design
+
+**Alias/hostname hosts move as-is.** They were already effectively pod-wide
+(the exact same set was redundantly re-emitted on every service's `run`
+line), so relocating them to `podman pod create` changes nothing observable
+except where the flag lives.
+
+**`extra_hosts` becomes a pod-level key, mirroring `dns`/`sysctls`:**
+- Removed from `SERVICE_KEYS` (`compose2pod/keys.py`) — no longer a
+  per-container emit. Its `_extra_host_pairs` normalizer (list → items,
+  mapping → `"host:ip"` strings, IPv6-safe) stays in `keys.py` and is now
+  imported by `pod.py`. `_emit_extra_hosts` (the old per-service Token
+  emitter) is deleted — dead once `extra_hosts` leaves `SERVICE_KEYS`.
+- Added to `STRUCTURAL_KEYS` (`compose2pod/keys.py`) so it stays a
+  recognized/supported service key.
+- Added to `_POD_OPTION_KEYS` (`compose2pod/pod.py`), so `uses_pod_options`
+  correctly fires the existing pod-wide-effects warning
+  (`compose2pod/parsing.py`) whenever any service declares it. The warning
+  text extends from `"dns/sysctls apply pod-wide ..."` to also name
+  `extra_hosts`/`/etc/hosts`.
+- Shape-checked in `validate_pod_options` (`compose2pod/pod.py`) via the
+  existing `_validate_map` (list or mapping) — moved out of the generic
+  `SERVICE_KEYS` validate loop, same relocation pattern as its emit.
+
+**Merge and conflict rule** (new `_add_host_flags` in `pod.py`, alongside
+`_dns_flags`/`_sysctl_flags`, folded into `pod_create_flags`, which gains a
+third `hosts: list[str]` parameter):
+- Seed the merged `{host: address}` map from the alias/hostname set (`hosts`,
+  computed once by `graph.hostnames`), all fixed at `127.0.0.1` — these can
+  never conflict with each other (same fixed value).
+- Layer each closure service's `extra_hosts` on top, closure-scoped exactly
+  like `dns`/`sysctls` (`order`, not the whole document).
+- A host name landing on two different addresses — from two services'
+  `extra_hosts`, or from an `extra_hosts` entry against an alias's fixed
+  `127.0.0.1` — raises `UnsupportedComposeError`, the same
+  refuse-rather-than-guess rule already used for a `sysctls` key conflict.
+  One rule for every host-merge source, no source-priority special-casing.
+
+**`run_flags` drops its `hosts` parameter entirely** (the add-host loop is
+deleted); `_run_tokens`, and the `_plan` call site, drop the argument too.
+`_plan` passes `hosts` (already computed for its own purposes) into
+`pod_create_flags` instead.
+
+## Non-goals
+
+- Per-service DNS/sysctls remain impossible inside a shared-namespace pod —
+  unrelated to this change, already documented.
+- No new validation of individual `extra_hosts` entry shape beyond "list or
+  mapping" (e.g. a colon-less list entry) — matches the pre-existing
+  shallow validation; podman surfaces a malformed entry at run time, as it
+  already would have.
+- No change to how aliases are collected (`graph.hostnames`) or scoped
+  (whole document, not closure-limited) — pre-existing, orthogonal behavior.
+
+## Testing
+
+`just test-ci` at 100%: `pod_create_flags` gains add-host cases (alias-only,
+extra_hosts-only, both merged, same-value dedup across sources, conflicting
+addresses refused — extra_hosts vs extra_hosts, and extra_hosts vs an alias);
+`run_flags` no longer emits `--add-host` for any input (extra_hosts or
+otherwise) and drops the `hosts` parameter at every call site; the
+whole-script tests (`test_add_host_on_every_run`,
+`test_hostname_becomes_add_host_entry`,
+`test_container_name_becomes_add_host_entry`,
+`test_image_host_metadata_keys_compose_on_one_service`) are re-pointed at the
+single `podman pod create` line instead of every `podman run` line; the
+`extra_hosts` cases inside `test_registry_emission_order_across_shape_groups`
+(a `SERVICE_KEYS` order-lock test) are removed, since `extra_hosts` is no
+longer a `SERVICE_KEYS` entry. `just lint-ci` and `just check-planning`
+clean. Final proof: the integration harness's three scenarios (PR #41) go
+green in the dedicated CI job against real podman.
+
+## Risk
+
+- **Silent conflict-detection gap** (low x high): a host conflict slips
+  through unmerged/undetected. Mitigated by one merge function, one rule,
+  exercised directly in `pod.py` unit tests plus the end-to-end
+  `emit_script` tests.
+- **Extra_hosts scope-broadening surprise** (med x low): a user relying on
+  today's genuinely-per-service `extra_hosts` gets a same-host conflict
+  error instead of silent divergence. Mitigated by the loud refusal (never a
+  silently wrong resolution) and the existing `uses_pod_options` warning
+  now also covering `extra_hosts`.