How to Set Up Custom DNS for Containers and Resolve Container Hostnames

You configure custom DNS for containers by defining a system-wide DNS domain in config.toml and managing host-side DNS entries through container system dns create, enabling automatic hostname resolution for both container names and external services.

The apple/container framework provides a built-in DNS resolver that eliminates the need for external DNS services when deploying containerized workloads. By leveraging the host-side configuration files and CLI tools, you can establish custom DNS for containers that automatically resolves container names and routes queries to external host addresses according to the implementation in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift.

Understanding the Built-in DNS Resolver

The container runtime implements a DNS server that handles hostname resolution through two distinct mechanisms. According to the source code in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift, the resolver listens on port 1053 when the host runs a DNS server, or port 2053 otherwise, and serves records from both the system configuration and dynamic host entries.

The Sources/ContainerPersistence/ContainerSystemConfig.swift implementation reads the [dns] section from the host configuration at startup, determining the default domain and resolver behavior for all containers.

Method 1: Configure a System-wide DNS Domain

You can define a default DNS domain that the resolver automatically appends to every container name. When configured, a container named my-web-server becomes reachable as my-web-server.<domain> within the container network.

Editing the Configuration File

Create or edit /etc/container/config.toml to include the [dns] section. The ContainerSystemConfig.swift implementation parses this file during daemon initialization as documented in docs/container-system-config.md.

[dns]
domain = "mycluster.local"

Reloading the Daemon

After modifying the configuration, reload the system to apply changes:

sudo container system reload

Once reloaded, any container you start will be reachable as <container-name>.mycluster.local from within other containers.

Method 2: Add Host-Side DNS Entries

For services running outside the container network, use the container system dns subcommands to create static mappings. These entries are stored in the runtime's DNS server and resolved alongside container hostnames, as detailed in docs/how-to.md and docs/command-reference.md.

Creating DNS Records

The container system dns create command maps a fully-qualified domain name to a specific IP address using the --localhost flag:

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

This creates a record that resolves my-db.internal to 192.168.1.42, allowing containers to reach external services without hardcoding IP addresses.

DNS Server Ports

The resolver implementation in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift handles queries on port 1053 when the host runs an existing DNS server, or port 2053 in standalone mode. Containers automatically forward DNS queries to this internal server regardless of the port used.

Complete Workflow Example

Follow these steps to configure a fully functional DNS environment for your containers:

1. Set the system-wide domain in /etc/container/config.toml:

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

2. Reload the daemon to apply the configuration:

sudo container system reload

3. Add a host-side entry for external service access:

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

4. Launch a container and verify resolution:

sudo container run --name webapp alpine sh -c 'ping -c 1 webapp.example.local'

Verifying DNS Configuration

To inspect all custom DNS records stored in the runtime, use the list command:

sudo container system dns list

This outputs all host-side entries that the resolver maintains, allowing you to verify that containers can resolve both internal hostnames and external service addresses.

Summary

• Configure the [dns] section in /etc/container/config.toml to establish a system-wide domain for automatic container hostname resolution.
• Use container system dns create with the --localhost flag to map external services to specific IP addresses accessible from containers.
• The DNS server implementation in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift listens on ports 1053 or 2053 depending on host configuration.
• Reload the daemon with sudo container system reload after modifying system-wide DNS settings in config.toml.
• Verify active records using sudo container system dns list to ensure containers can resolve both internal and external hostnames.

Frequently Asked Questions

How do I set a custom DNS domain for all containers?

Set the domain key in the [dns] section of /etc/container/config.toml, then run sudo container system reload. The ContainerSystemConfig.swift implementation reads this value during daemon startup and configures the resolver to append the domain to all container names automatically.

What port does the container DNS server use?

The resolver listens on port 1053 when the host already runs a DNS server, otherwise it uses port 2053. This behavior is implemented in Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift to avoid conflicts with existing host DNS services.

How do I resolve hostnames for services outside the container network?

Use sudo container system dns create <hostname> --localhost <ip> to add static DNS entries. These mappings are stored in the runtime's DNS server and allow containers to resolve external service addresses without modifying the host's system-wide DNS configuration.

Where is the DNS configuration stored?

System-wide settings are defined in /etc/container/config.toml and parsed by Sources/ContainerPersistence/ContainerSystemConfig.swift. Host-side DNS entries are managed through the container system dns commands and persisted within the container runtime's internal state, separate from the host's /etc/hosts or system resolver.

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