|
| 1 | +--- |
| 2 | +summary: Accept the service `hostname` key, resolving it to 127.0.0.1 like a network alias. |
| 3 | +--- |
| 4 | + |
| 5 | +# Design: Support the service `hostname` key |
| 6 | + |
| 7 | +## Summary |
| 8 | + |
| 9 | +compose2pod rejects any service key it does not explicitly support, so a |
| 10 | +service that sets `hostname:` fails with |
| 11 | +`service 'keydb': unsupported key 'hostname'`. This change adds `hostname` to |
| 12 | +the supported service keys and folds each service's hostname into |
| 13 | +`graph.hostnames()`, so it becomes an `--add-host <hostname>:127.0.0.1` entry |
| 14 | +exactly like a network alias. The change touches `compose2pod/parsing.py` and |
| 15 | +`compose2pod/graph.py`, plus the `architecture/supported-subset.md` promotion. |
| 16 | + |
| 17 | +## Motivation |
| 18 | + |
| 19 | +A real-world CI compose file sets a hostname on its KeyDB service: |
| 20 | + |
| 21 | +```yaml |
| 22 | +keydb: |
| 23 | + image: .../keydb-for-ci:x86_64_v6.3.0 |
| 24 | + hostname: keydb-test-server-0 |
| 25 | + restart: always |
| 26 | +``` |
| 27 | +
|
| 28 | +The application connects to KeyDB at `keydb-test-server-0`, so that name is |
| 29 | +**load-bearing** — if it does not resolve to the pod's shared loopback, the |
| 30 | +connection fails. `validate()` (`parsing.py:57`) rejects the document outright |
| 31 | +because `hostname` is in neither `SUPPORTED_SERVICE_KEYS` nor |
| 32 | +`IGNORED_SERVICE_KEYS`. |
| 33 | + |
| 34 | +This is the same reachability need compose2pod already serves for network |
| 35 | +aliases: `hostnames()` collects service names and `networks[*].aliases`, and |
| 36 | +`emit.run_flags` emits `--add-host <name>:127.0.0.1` for each so every |
| 37 | +container in the shared network namespace resolves those names to loopback. |
| 38 | +The `chats_compose` test fixture even models this exact hostname |
| 39 | +(`keydb-test-server-0`) as a network alias today; the only gap is the `hostname` |
| 40 | +spelling of the same intent. |
| 41 | + |
| 42 | +## Design |
| 43 | + |
| 44 | +### 1. Accept `hostname` as a supported service key (`parsing.py`) |
| 45 | + |
| 46 | +Add `"hostname"` to `SUPPORTED_SERVICE_KEYS`. No dedicated validation: the value |
| 47 | +is a plain string consumed by `hostnames()`, handled identically to alias |
| 48 | +strings (which carry no type validation either). |
| 49 | + |
| 50 | +### 2. Collect the hostname in `graph.hostnames()` |
| 51 | + |
| 52 | +Inside the existing per-service loop, append `svc.get("hostname")` when present, |
| 53 | +alongside the alias collection: |
| 54 | + |
| 55 | +```python |
| 56 | +for svc in services.values(): |
| 57 | + hostname = svc.get("hostname") |
| 58 | + if hostname: |
| 59 | + names.append(hostname) |
| 60 | + networks = svc.get("networks") |
| 61 | + ... |
| 62 | +``` |
| 63 | + |
| 64 | +The hostname joins the flat, pod-global host list, so every container gets an |
| 65 | +`--add-host <hostname>:127.0.0.1` entry — the correct behavior in a single |
| 66 | +shared-namespace pod, where all inter-service traffic is loopback. |
| 67 | + |
| 68 | +### 3. Promote into `architecture/supported-subset.md` |
| 69 | + |
| 70 | +Add `hostname` to the Supported service keys list, with a note that it is made |
| 71 | +resolvable to loopback like a network alias (the pod shares the UTS namespace, |
| 72 | +so the container's own hostname is the pod's; only name resolution is |
| 73 | +meaningful). |
| 74 | + |
| 75 | +## Non-goals |
| 76 | + |
| 77 | +- **No per-container `--hostname` flag.** Pod members share the UTS namespace by |
| 78 | + default, so a per-service hostname is not settable/meaningful; only name |
| 79 | + resolution matters, and `--add-host` covers it. |
| 80 | +- **Not "ignore with a warning"** (the `ports`/`restart` treatment). The |
| 81 | + hostname is load-bearing — dropping it silently would emit a script that |
| 82 | + fails at connect time, violating the "refuse loudly, never silently drop |
| 83 | + behavior" principle. It is genuinely supported, not ignored. |
| 84 | +- No change to how aliases or any other service key are handled. |
| 85 | + |
| 86 | +## Testing |
| 87 | + |
| 88 | +TDD, and `just test-ci` must stay at 100% line coverage. |
| 89 | + |
| 90 | +- Unit (`test_parsing.py`): a service with `hostname` validates without raising. |
| 91 | +- Unit (`test_graph.py`): `hostnames()` includes a service's `hostname` value in |
| 92 | + its output. |
| 93 | +- Integration (`test_emit.py`): a compose document with `hostname: <h>` |
| 94 | + round-trips through `validate` → `emit_script` and the rendered script |
| 95 | + contains `--add-host <h>:127.0.0.1`. |
| 96 | + |
| 97 | +## Risk |
| 98 | + |
| 99 | +Low. The change mirrors an established, tested mechanism (network aliases) and |
| 100 | +is confined to two small edits plus a doc promotion. The main risk is a |
| 101 | +hostname colliding with an existing service name or alias, producing a duplicate |
| 102 | +`--add-host` for the same loopback target — harmless (identical mapping), and no |
| 103 | +worse than the existing duplicate-alias possibility. |
0 commit comments