[Request]: Consider documenting the "FQDN/search-domain flows" for container-to-container networking on a custom network
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
### Feature or enhancement request details
Moved to an issue per @saehejkang 's suggestion in #2238.
Both the recently refactored [networking docs](https://github.com/apple/container/blob/main/docs/networking.md#container-to-container-networking) and the more recently added [skills](https://github.com/apple/container/blob/main/skills/container/references/docker-migration.md#replacing-a-compose-file) states that "container-to-container networking"
> ... does not ... work for ... container(s) ... on a custom network ... that gap is tracked ... as https://github.com/apple/container/issues/1809
This seems too strong a claim given in #1809 it was mentioned:
> ... configuring a DNS domain with `container system dns create ` plus setting `dns.domain` ... can make FQDN/search-domain flows work ...
I believe the "FQDN/search-domain flows" here would be sth. like this:
```shell
% container network create foo
foo
% container run --rm -d --dns-search=foo.test --dns-search=test --name http-server.foo.test --network foo python:alpine python3 -m http.server
http-server.foo.test
% container run -it --rm --dns-search=foo.test --dns-search=test --network foo alpine/curl curl -v http://http-server.foo.test:8000
* ...
* Host http-server.foo.test:8000 was resolved.
* IPv6: ...
* IPv4: 192.168.65.2
* Trying 192.168.65.2:8000...
* Established connection to http-server.foo.test (192.168.65.2 port 8000) from 192.168.65.3 port 39362
* using HTTP/1.x
> GET / HTTP/1.1
> Host: http-server.foo.test:8000
> User-Agent: curl/8.21.0
> Accept: */*
>
* Request completely sent off
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Server: SimpleHTTP/0.6 Python/3.13.15
< Date: Fri, 04 Sep 2026 10:32:58 GMT
< Content-type: text/html; charset=utf-8
< Content-Length: 809
<
...
* shutting down connection #0
```
In fact, even the "looking up another container by its _bare_ hostname" works, to some extent:
```shell
% container run -it --rm --dns-search=foo.test --dns-search=test --network foo alpine/curl curl -v http://http-server:8000
* Host http-server:8000 was resolved.
* IPv6: ...
* IPv4: 192.168.65.2
* ...
* Trying 192.168.65.2:8000...
* Established connection to http-server (192.168.65.2 port 8000) from 192.168.65.4 port 54438
* using HTTP/1.x
> GET / HTTP/1.1
> Host: http-server:8000
> User-Agent: curl/8.21.0
> Accept: */*
>
* Request completely sent off
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Server: SimpleHTTP/0.6 Python/3.13.15
< Date: Fri, 04 Sep 2026 10:33:05 GMT
< Content-type: text/html; charset=utf-8
< Content-Length: 809
<
...
* shutting down connection #0
```
I understand that passing the configured domain in both `--dns-search` options and a longer FQDN like id/name takes a lot of typing and is far from ideal, but if it is already possible, maybe it should be documented? At least in the skills, since a coding agent should not mind the extra "typing"?
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
Contributor guide
Research direction
Read docs/networking.md and skills/container/references/docker-migration.md, then reproduce the FQDN and bare-hostname examples from the issue on a custom network. Document the supported DNS/search-domain flow and its caveats, and revise the existing claim so both pages accurately describe what works.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, shell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100