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

> Configure custom DNS for containers and resolve hostnames efficiently. Learn to manage DNS entries and enable automatic resolution for container and external services.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-11

---

**You configure custom DNS for containers by defining a system-wide DNS domain in [`config.toml`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main//etc/container/config.toml) to include the `[dns]` section. The [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) implementation parses this file during daemon initialization as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

```toml
[dns]
domain = "mycluster.local"

```

### Reloading the Daemon

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

```bash
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`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/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:

```bash
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main//etc/container/config.toml):

```bash
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:

```bash
sudo container system reload

```

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

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

```

4. Launch a container and verify resolution:

```bash
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:

```bash
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`](https://github.com/apple/container/blob/main//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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main//etc/container/config.toml), then run `sudo container system reload`. The [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main//etc/container/config.toml) and parsed by [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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.