Skip to content

Commit 3e30963

Browse files
authored
feat: support the service hostname key (#8)
* docs: plan service hostname key support * feat: accept service 'hostname' key in validate * feat: collect service hostname as a resolvable pod host * feat: document and cover service hostname pod-host resolution * test: round-trip validate in hostname emit test and cover empty hostname
1 parent 9aa52ba commit 3e30963

7 files changed

Lines changed: 150 additions & 5 deletions

File tree

‎architecture/supported-subset.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,15 @@ warns (ignored, behavior-neutral inside a single pod) or raises
2020
## Service keys
2121

2222
- **Supported:** `image`, `build`, `command`, `environment`, `env_file`,
23-
`volumes`, `healthcheck`, `depends_on`, `networks`. compose2pod never builds:
24-
a `build` section is accepted but its contents (context, dockerfile, args) are
25-
not read — `image_for` (`compose2pod/emit.py`) runs the CI image supplied via
26-
`--image` for any service that has one.
23+
`volumes`, `healthcheck`, `depends_on`, `networks`, `hostname`. compose2pod
24+
never builds: a `build` section is accepted but its contents (context,
25+
dockerfile, args) are not read — `image_for` (`compose2pod/emit.py`) runs
26+
the CI image supplied via `--image` for any service that has one.
27+
- **`hostname`:** the service's hostname is made resolvable to `127.0.0.1`
28+
like a network alias (added to the shared `--add-host` set), so other
29+
services can reach it by that name. The pod shares the UTS namespace, so a
30+
service's own hostname is the pod's; only name resolution is meaningful,
31+
and no per-container `--hostname` is emitted.
2732
- **Ignored (warns):** `ports`, `restart`, `stdin_open`, `tty` — meaningless
2833
or irrelevant inside a single shared-namespace pod.
2934
- **Extension fields:** any `x-`-prefixed service key is accepted and ignored

‎compose2pod/graph.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,12 @@ def depends_on(svc: dict[str, Any]) -> dict[str, str]:
1414

1515

1616
def hostnames(services: dict[str, Any]) -> list[str]:
17-
"""All names other services may use to reach a service: names, then aliases."""
17+
"""All names other services may use to reach a service: names, hostnames, then aliases."""
1818
names = list(services)
1919
for svc in services.values():
20+
hostname = svc.get("hostname")
21+
if hostname:
22+
names.append(hostname)
2023
networks = svc.get("networks")
2124
if isinstance(networks, dict):
2225
for network in networks.values():

‎compose2pod/parsing.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
"healthcheck",
1818
"depends_on",
1919
"networks",
20+
"hostname",
2021
}
2122
IGNORED_SERVICE_KEYS = {"ports", "restart", "stdin_open", "tty"}
2223
SUPPORTED_HEALTHCHECK_KEYS = {"test", "interval", "timeout", "retries", "start_period"}
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
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.

‎tests/test_emit.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
image_for,
66
run_flags,
77
)
8+
from compose2pod.parsing import validate
89

910

1011
_EXPECTED_RUN_LINES: int = 4
@@ -140,6 +141,26 @@ def test_wait_healthy_function_uses_healthcheck_run(self, chats_compose: dict) -
140141
assert "podman healthcheck run" in script
141142
assert "wait_healthy()" in script
142143

144+
def test_hostname_becomes_add_host_entry(self) -> None:
145+
compose = {
146+
"services": {
147+
"application": {"image": "app", "depends_on": ["keydb"]},
148+
"keydb": {"image": "keydb", "hostname": "keydb-test-server-0"},
149+
}
150+
}
151+
options = EmitOptions(
152+
target="application",
153+
ci_image="ci",
154+
command="",
155+
pod="testpod",
156+
project_dir="/proj",
157+
artifacts=[],
158+
allow_exit_codes=[],
159+
)
160+
assert validate(compose) == []
161+
script = emit_script(compose=compose, options=options)
162+
assert "--add-host keydb-test-server-0:127.0.0.1" in script
163+
143164
def test_target_without_command_uses_service_command(self, chats_compose: dict) -> None:
144165
options = EmitOptions(
145166
target="application",

‎tests/test_graph.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ def test_non_dict_network_entry_is_skipped(self) -> None:
2929
services = {"app": {"image": "x", "networks": {"default": None, "other": {"aliases": ["app-alias"]}}}}
3030
assert hostnames(services) == ["app", "app-alias"]
3131

32+
def test_collects_service_hostname(self) -> None:
33+
services = {"keydb": {"image": "x", "hostname": "keydb-test-server-0"}}
34+
assert hostnames(services) == ["keydb", "keydb-test-server-0"]
35+
36+
def test_empty_hostname_is_skipped(self) -> None:
37+
services = {"a": {"image": "x", "hostname": ""}}
38+
assert hostnames(services) == ["a"]
39+
3240

3341
class TestStartupOrder:
3442
def test_chats_order(self, chats_compose: dict) -> None:

‎tests/test_parsing.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,3 +107,7 @@ def test_service_extension_key_is_accepted_silently(self) -> None:
107107
def test_healthcheck_extension_key_is_accepted(self) -> None:
108108
compose = {"services": {"app": {"image": "x", "healthcheck": {"test": "true", "x-note": "n"}}}}
109109
assert validate(compose) == []
110+
111+
def test_service_hostname_is_accepted(self) -> None:
112+
compose = {"services": {"keydb": {"image": "x", "hostname": "keydb-test-server-0"}}}
113+
assert validate(compose) == []

0 commit comments

Comments
 (0)