Skip to main content
Uncloud provides two DNS systems to make your services accessible by name:
  1. Internal DNS - Resolves service names to container IPs within the cluster
  2. Managed DNS - Provides *.uncld.dev domains for public internet access

​
Internal DNS

Every Uncloud machine runs a built-in DNS server that resolves service names to container IP addresses. This allows containers to discover and communicate with each other across machines.

​
Service name resolution

Services are accessible at <service-name>.internal: 
# From within a container
curl http://web-api.internal:8000
When you query a service name, the DNS server returns all container IPs for that service: 
# Service with 3 replicas across machines
nslookup web-api.internal
# Returns:
# 10.210.0.5
# 10.210.1.8
# 10.210.2.12
Your application can use this for client-side load balancing or simply let the DNS resolver pick one.

​
Service ID resolution

You can also resolve services by their ID: 
curl http://abc123-service-id.internal:8000
This is useful when you have services with the same name (from different deployments) and need to target a specific one.

​
Machine-specific resolution

Need to reach a service on a specific machine? Use the machine-specific DNS format: 
<machine-id>.m.<service-name>.internal
Example: 
# Connect to the web-api container on machine abc123
curl http://abc123.m.web-api.internal:8000
This returns only the container IP on that specific machine, useful for:
  • Debugging specific machine issues
  • Draining traffic from a machine before maintenance
  • Sticky sessions or affinity requirements

​
Nearest mode

Want to prefer local containers? Use the nearest prefix: 
curl http://nearest.web-api.internal:8000
The DNS server sorts results to return containers on the same machine first, reducing network latency. If no local containers exist, it returns all container IPs as usual.

​
DNS configuration

Containers automatically use the internal DNS server. Docker sets it up when containers join the Uncloud network. You can verify DNS configuration inside a container: 
uc service exec web-api cat /etc/resolv.conf
You should see the machine’s WireGuard IP (usually 10.210.X.1) as the nameserver.

​
Managed DNS (*.uncld.dev)

Uncloud provides free *.uncld.dev subdomains for your clusters through the Uncloud DNS service. This eliminates the need to configure your own DNS records for development and testing.

​
Reserving a domain

Reserve a unique subdomain for your cluster: 
uc dns reserve
Example output: 
Reserved cluster domain: xuw3xd.uncld.dev
The domain is randomly generated and unique to your cluster. All services can use wildcard subdomains under this domain:
  • web.xuw3xd.uncld.dev
  • api.xuw3xd.uncld.dev
  • admin.xuw3xd.uncld.dev
During cluster initialization with uc machine init, a domain is automatically reserved unless you use --no-dns.

​
Checking your domain

View your cluster’s reserved domain: 
uc dns show
Example output: 
xuw3xd.uncld.dev
If no domain is reserved, you’ll see: 
no domain reserved

​
Releasing a domain

Release your cluster’s domain when you no longer need it: 
uc dns release
Example output: 
Released cluster domain: xuw3xd.uncld.dev
The domain becomes available for other clusters to use.
No. Domains are randomly generated to ensure uniqueness and availability. This prevents domain squatting and makes the system fair for everyone.For custom domains, see the Custom Domain Setup section below.

​
DNS record updates

Uncloud automatically updates DNS records to point to machines running Caddy containers. This happens when:
  • You reserve a domain with uc dns reserve
  • You deploy Caddy with uc caddy deploy
  • You add a machine with uc machine add
Uncloud verifies which machines are reachable from the internet by sending HTTP requests to their public IPs. Only reachable machines are included in DNS records. Example: 
Updating cluster domain records in Uncloud DNS to point to machines running caddy service...
[+] Verifying internet access to caddy service 2/2
 ✔ Machine hetzner-server (5.223.45.199)  Reachable
 ✔ Machine oracle-vm (152.67.101.197)     Reachable

DNS records updated to use only the internet-reachable machines running caddy service:
  *.xuw3xd.uncld.dev  A → 152.67.101.197, 5.223.45.199
If no machines are reachable, you’ll see a warning with troubleshooting steps.

​
DNS propagation

Changes to *.uncld.dev records propagate quickly (usually within seconds) because the Uncloud DNS service uses low TTL values. You can verify DNS resolution: 
dig web.xuw3xd.uncld.dev

​
Custom domain setup

While *.uncld.dev domains are convenient for development, you’ll want to use your own domain for production.

​
Prerequisites

  • A domain name you own (e.g., example.com)
  • Access to your domain’s DNS settings
  • At least one machine with a public IP running Caddy

​
Step 1: Deploy your service

Deploy your service with your custom domain: 
uc run -p app.example.com:8000/https image/my-app
Or in a compose.yaml: 
services:
  web:
    image: image/my-app
    ports:
      - app.example.com:8000/https

​
Step 2: Create DNS records

Create A (for IPv4) or AAAA (for IPv6) records pointing to your machines’ public IPs: For a single machine: 
Type: A
Name: app
Value: 203.0.113.10
TTL: 3600
For multiple machines (load balancing): 
Type: A
Name: app
Value: 203.0.113.10
TTL: 3600

Type: A
Name: app
Value: 203.0.113.20
TTL: 3600
DNS resolvers will round-robin between the IPs. For wildcard subdomains: 
Type: A
Name: *
Value: 203.0.113.10
TTL: 3600
This allows any subdomain (like api.example.com, admin.example.com) to resolve to your machine.

​
Step 3: Wait for propagation

DNS changes can take anywhere from a few minutes to 48 hours to propagate globally, depending on your DNS provider and TTL settings. Check DNS propagation: 
dig app.example.com
Once DNS resolves correctly, Caddy will automatically obtain and configure a Let’s Encrypt TLS certificate for your domain.

​
Multiple domains for one service

You can expose a service on multiple domains: 
uc run -p app.example.com:8000/https -p www.example.com:8000/https image/my-app
Or in compose.yaml: 
services:
  web:
    image: image/my-app
    ports:
      - app.example.com:8000/https
      - www.example.com:8000/https

​
Apex domain (example.com)

To use your apex domain (without www or other subdomain): 
uc run -p example.com:8000/https image/my-app
Create an A record for the apex: 
Type: A
Name: @
Value: 203.0.113.10
TTL: 3600
If your DNS records aren’t resolving after a day:
  1. Verify the DNS record in your provider’s dashboard
    • Make sure you created an A record (not CNAME)
    • Double-check the IP address is correct
    • Verify there are no typos in the domain name
  2. Check DNS propagation 
    dig app.example.com @8.8.8.8
    Use Google’s DNS (8.8.8.8) or Cloudflare’s (1.1.1.1) to check global propagation
  3. Clear your local DNS cache 
    # macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns
  4. Contact your DNS provider Some providers have additional verification steps or restrictions on certain record types

​
DNS best practices

​
Use managed DNS for development

The free *.uncld.dev domains are perfect for:
  • Development environments
  • Testing deployments
  • Preview branches
  • Internal tools that don’t need a custom domain

​
Use custom domains for production

For production workloads:
  • Use your own domain name
  • Configure proper TTL values (3600 seconds is a good default)
  • Set up multiple A records for high availability
  • Consider using a CDN like Cloudflare for DDoS protection

​
Monitor DNS health

Regularly check that your DNS records point to reachable machines: 
uc machine ls  # Check which machines are Up
dig app.example.com  # Verify DNS resolution
If you remove or replace a machine, update your DNS records accordingly.

​
DNS command reference

CommandDescription
uc dns reserveReserve a *.uncld.dev subdomain for your cluster
uc dns showDisplay your cluster’s reserved domain
uc dns releaseRelease your cluster’s domain
uc dns reserve --endpoint URLUse a custom Uncloud DNS API endpoint

​
Next steps

Caddy Proxy

Configure HTTPS and reverse proxy

Troubleshooting

Debug DNS and connectivity issues

Build docs developers (and LLMs) love

Get started for freeTalk to us