Skip to content

Commit 2a9528b

Browse files
authored
feat: support the service container_name key (#12)
* docs: plan container_name support * feat: accept and resolve the service container_name key Mirrors the existing hostname support: container_name is accepted in validate() and folded into graph.hostnames(), so it becomes an --add-host <name>:127.0.0.1 entry. The actual podman container is still named {pod}-{service} internally; only name resolution is affected.
1 parent 5bed4db commit 2a9528b

7 files changed

Lines changed: 103 additions & 10 deletions

File tree

‎architecture/supported-subset.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,19 @@ 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`, `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.
23+
`volumes`, `healthcheck`, `depends_on`, `networks`, `hostname`,
24+
`container_name`. compose2pod never builds: a `build` section is accepted
25+
but its contents (context, dockerfile, args) are not read — `image_for`
26+
(`compose2pod/emit.py`) runs the CI image supplied via `--image` for any
27+
service that has one.
28+
- **`hostname` and `container_name`:** both are made resolvable to
29+
`127.0.0.1` like a network alias (added to the shared `--add-host` set), so
30+
other services can reach the service by either name. The pod shares the UTS
31+
namespace, so a service's own hostname is the pod's, and the actual podman
32+
container is always named `{pod}-{service}` regardless of `container_name`
33+
(used internally for `podman cp`, healthcheck polling, and target-container
34+
diagnostics) — only name *resolution* is meaningful to other services, and
35+
no per-container `--hostname` or renamed `--name` is emitted.
3236
- **Ignored (warns):** `ports`, `restart`, `stdin_open`, `tty` — meaningless
3337
or irrelevant inside a single shared-namespace pod.
3438
- **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,12 +14,15 @@ 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, hostnames, then aliases."""
17+
"""All names other services may use to reach a service: names, hostnames/container names, then aliases."""
1818
names = list(services)
1919
for svc in services.values():
2020
hostname = svc.get("hostname")
2121
if hostname:
2222
names.append(hostname)
23+
container_name = svc.get("container_name")
24+
if container_name:
25+
names.append(container_name)
2326
networks = svc.get("networks")
2427
if isinstance(networks, dict):
2528
for network in networks.values():

‎compose2pod/parsing.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"depends_on",
1919
"networks",
2020
"hostname",
21+
"container_name",
2122
}
2223
IGNORED_SERVICE_KEYS = {"ports", "restart", "stdin_open", "tty"}
2324
SUPPORTED_HEALTHCHECK_KEYS = {"test", "interval", "timeout", "retries", "start_period"}
Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
summary: Accept the service `container_name` key, resolving it to 127.0.0.1 like `hostname` and network aliases.
3+
---
4+
5+
# Change: Support the service `container_name` key
6+
7+
**Lane:** lightweight — two files (`parsing.py`, `graph.py`), no new file, no
8+
public-API change, mirrors the already-shipped `hostname` support exactly.
9+
10+
## Goal
11+
12+
`validate()` rejects the service `container_name` key
13+
(`service 'application': unsupported key 'container_name'`). A real compose
14+
file sets `container_name: calutron-ronline` and other services (or the host
15+
tooling) reach it by that name — the reporting user confirmed it is "also used
16+
as hostname." Fix: accept `container_name` and make it resolvable to loopback,
17+
the same treatment `hostname` already gets.
18+
19+
## Approach
20+
21+
Same shape as the `hostname` change
22+
(`planning/changes/2026-07-08.01-service-hostname.md`):
23+
24+
- `parsing.py`: add `"container_name"` to `SUPPORTED_SERVICE_KEYS`.
25+
- `graph.py`: `hostnames()` also collects `svc.get("container_name")`
26+
(truthy-guarded, same pattern as `hostname`), so it becomes an
27+
`--add-host <container_name>:127.0.0.1` entry.
28+
29+
Explicitly **not** changed: `emit.run_flags` keeps naming the actual podman
30+
container `{pod}-{name}` (`emit.py:47`) — that internal name is what
31+
`podman cp`, the healthcheck `wait_healthy` calls, and the target-container
32+
inspect/log calls all reference. Renaming the real `--name` to the compose
33+
`container_name` would require rewiring every one of those references for no
34+
resolution benefit: the pod's shared UTS/network namespace means only name
35+
*resolution* is meaningful to other services, not the literal running
36+
container's identity, which `--add-host` already supplies.
37+
38+
## Non-goals
39+
40+
- No `podman run --name <container_name>` — see rationale above.
41+
- No uniqueness/collision validation between `container_name`, `hostname`, and
42+
service names — `hostnames()` already tolerates duplicate entries (harmless
43+
repeated `--add-host` of the same loopback mapping), consistent with the
44+
`hostname` change's accepted risk.
45+
46+
## Testing
47+
48+
TDD, `just test-ci` at 100% line coverage.
49+
50+
- Unit (`test_parsing.py`): a service with `container_name` validates without raising.
51+
- Unit (`test_graph.py`): `hostnames()` includes a service's `container_name`.
52+
- Integration (`test_emit.py`): `container_name` round-trips through
53+
`validate` → `emit_script` and the rendered script contains
54+
`--add-host <name>:127.0.0.1`.
55+
56+
## Risk
57+
58+
Low — identical mechanism to the already-shipped, tested `hostname` support.

‎tests/test_emit.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,25 @@ def test_hostname_becomes_add_host_entry(self) -> None:
165165
script = emit_script(compose=compose, options=options)
166166
assert "--add-host keydb-test-server-0:127.0.0.1" in script
167167

168+
def test_container_name_becomes_add_host_entry(self) -> None:
169+
compose = {
170+
"services": {
171+
"application": {"image": "app", "container_name": "calutron-ronline"},
172+
}
173+
}
174+
options = EmitOptions(
175+
target="application",
176+
ci_image="ci",
177+
command="",
178+
pod="testpod",
179+
project_dir="/proj",
180+
artifacts=[],
181+
allow_exit_codes=[],
182+
)
183+
assert validate(compose) == []
184+
script = emit_script(compose=compose, options=options)
185+
assert "--add-host calutron-ronline:127.0.0.1" in script
186+
168187
def test_target_without_command_uses_service_command(self, chats_compose: dict) -> None:
169188
options = EmitOptions(
170189
target="application",

‎tests/test_graph.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ def test_collects_service_hostname(self) -> None:
3333
services = {"keydb": {"image": "x", "hostname": "keydb-test-server-0"}}
3434
assert hostnames(services) == ["keydb", "keydb-test-server-0"]
3535

36+
def test_collects_service_container_name(self) -> None:
37+
services = {"application": {"image": "x", "container_name": "calutron-ronline"}}
38+
assert hostnames(services) == ["application", "calutron-ronline"]
39+
3640
def test_empty_hostname_is_skipped(self) -> None:
3741
services = {"a": {"image": "x", "hostname": ""}}
3842
assert hostnames(services) == ["a"]

‎tests/test_parsing.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,7 @@ def test_healthcheck_extension_key_is_accepted(self) -> None:
118118
def test_service_hostname_is_accepted(self) -> None:
119119
compose = {"services": {"keydb": {"image": "x", "hostname": "keydb-test-server-0"}}}
120120
assert validate(compose) == []
121+
122+
def test_service_container_name_is_accepted(self) -> None:
123+
compose = {"services": {"application": {"image": "x", "container_name": "calutron-ronline"}}}
124+
assert validate(compose) == []

0 commit comments

Comments
 (0)