How to Configure Custom DNS for Containers Using Container System DNS Commands

You can configure custom DNS for containers by setting a system-wide domain in /etc/container/config.toml and using container system dns create commands to map hostnames to IP addresses that the built-in resolver serves on ports 1053 or 2053.

The apple/container project includes a built-in DNS resolver that enables automatic container name resolution and custom hostname mappings without external services. You configure custom DNS for containers using container system dns commands and the [dns] section in the host-side TOML configuration. This setup allows containers to resolve each other by name and reach external services through custom host entries.

Understanding the Container DNS Architecture

The container runtime implements a DNS server that operates on port 1053 when the host runs a DNS server, or port 2053 otherwise. According to the implementation in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift, this resolver handles two types of queries: automatic container name resolution with an optional domain suffix, and static host entries created via the CLI.

System-Wide DNS Domain

The domain setting in config.toml automatically appends a DNS suffix to every container name. When set to mycluster.local, the container my-web-server becomes reachable as my-web-server.mycluster.local. This configuration is parsed by Sources/ContainerPersistence/ContainerSystemConfig.swift as documented in docs/container-system-config.md.

Host-Side DNS Entries

The container system dns sub-commands manage static mappings between fully-qualified domain names and specific IP addresses. These entries allow containers to resolve hostnames for services running outside the container network, such as host.container.internal pointing to 203.0.113.113.

Setting a System-Wide DNS Domain

Configuring config.toml

Create or edit /etc/container/config.toml to include the [dns] section. The Swift model in Sources/ContainerPersistence/ContainerSystemConfig.swift reads this configuration during daemon startup:

[dns]
domain = "example.local"

Reloading the Daemon

Apply the new DNS configuration by reloading the container system:

sudo container system reload

After reloading, any container you start will be reachable as <container-name>.example.local from within other containers.

Managing Host-Side DNS Entries with Container System DNS Commands

Creating DNS Records

Use container system dns create to map a hostname to a specific IP address. This stores the entry in the container runtime's DNS server as described in docs/how-to.md and docs/command-reference.md:

sudo container system dns create my-db.internal --localhost 192.168.1.42

The --localhost flag specifies the target IP address. You can use any fully-qualified domain name as the hostname.

Verifying Configuration

Confirm your custom DNS configuration is active using the list command:

sudo container system dns list

This outputs all custom host entries that the container DNS server maintains, showing the mappings created via container system dns create.

Complete Walkthrough Example

Combine both mechanisms to create a fully functional custom DNS environment:

# 1. Configure the system-wide domain

sudo mkdir -p /etc/container
sudo tee /etc/container/config.toml > /dev/null <<'EOF'
[dns]
domain = "mycluster.local"
EOF

# 2. Apply the configuration

sudo container system reload

# 3. Add a host-side entry for external services

sudo container system dns create host.container.internal --localhost 203.0.113.113

# 4. Run a container

sudo container run --name webapp

# 5. Verify DNS resolution inside a new container

sudo container run --rm alpine sh -c 'ping -c 1 webapp.mycluster.local && ping -c 1 host.container.internal'

# 6. List all custom DNS records

sudo container system dns list

Inside containers, webapp.mycluster.local resolves to the container's IP, while host.container.internal resolves to the host-side IP you configured.

Summary

• System-wide domain: Set the domain key in /etc/container/config.toml under [dns] to enable automatic FQDN resolution for all containers.
• Host-side entries: Use sudo container system dns create <hostname> --localhost <ip> to map custom hostnames to specific IP addresses.
• Verification: Run sudo container system dns list to inspect active DNS records stored by the runtime.
• Implementation: The DNS server implementation resides in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift, while configuration parsing is handled by Sources/ContainerPersistence/ContainerSystemConfig.swift.

Frequently Asked Questions

Where does the container DNS server listen?

The container DNS server listens on port 1053 when the host runs a DNS server, otherwise on port 2053. This behavior is implemented in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift.

Do I need external DNS services to resolve container hostnames?

No. The apple/container project provides a built-in resolver that handles both automatic container name resolution and custom entries created via container system dns commands without requiring external DNS configuration or separate DNS servers.

What file format does the container system use for DNS configuration?

The system uses TOML format in /etc/container/config.toml. The [dns] section accepts a domain key that defines the default search domain for all containers, as parsed by Sources/ContainerPersistence/ContainerSystemConfig.swift according to the schema in docs/container-system-config.md.

How do I remove a custom DNS entry?

While the provided examples demonstrate creating entries, the container system dns command family includes management sub-commands documented in docs/command-reference.md. Consult that reference for the specific syntax to delete or modify entries created with container system dns create.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}