apple / apple/container

[Request]: Consider documenting the "FQDN/search-domain flows" for container-to-container networking on a custom network

Open Beginner friendly
#2,239 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.