# ZDNS Service

## Overview

Zenlayer DNS (ZDNS) is a highly available DNS service with **global configuration and regional delivery** provided by Zenlayer Elastic Compute.

The ZDNS cluster uses a stateless architecture, where each server can independently handle DNS queries. All servers in the cluster advertise the same VIP via BGP. If a node becomes unhealthy, its BGP advertisement is automatically withdrawn, and traffic is routed to other healthy nodes—ensuring high availability.

The ZDNS uses TCP/UDP port 53 by default, with the following resolver addresses:

* **IPv4**: `169.254.169.253`
* **IPv6**: `fd00:a9fe:a9fd::1`

ZDNS supports both **private domain resolution** and **public recursive resolution**. The private DNS feature enables service discovery, load balancing, and high availability. You can also use private DNS records to centrally manage various cloud resources within a VPC—such as cloud servers and load balancers—enhancing resource management efficiency and overall service reliability.

<div align="left"><figure><img src="https://3201622183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9X3FDdkCL2HzhbPpPMFt%2Fuploads%2FloBuDGlo16JyrIhQA76Y%2Fimage-20251126-035508.png?alt=media&#x26;token=f1cf7e80-0980-433c-be1a-35b2f3faed1a" alt="" width="563"><figcaption></figcaption></figure></div>

## Features

* **High Availability**: Single-node failures do not affect overall DNS resolution, as traffic automatically shifts to healthy nodes.
* **Stateless Architecture**: Nodes can be added or removed quickly without global state synchronization.
* **Horizontal Scalability**: Adding new nodes immediately increases the cluster’s processing capacity.
* **VPC Isolation**: Supports authoritative DNS resolution for private domains across different VPCs.
* **Public Recursive Resolution**: Performs public recursive queries for domain names that miss in the local zone.
* **Private Subdomain Recursive Fallback**: When a private authoritative parent domain matches but the subdomain does not, the system automatically falls back to public recursive resolution.

## ZDNS Resolution Workflow

1. **Client Configuration**\
   The client (VM) should configure the DNS server addresses as follows:
   * **IPv4**: `169.254.169.253`
   * **IPv6**: `fd00:a9fe:a9fd::1`
2. **Request Ingress**\
   When the client sends DNS queries to the above addresses, the requests are routed to the ZDNS cluster in the corresponding region.
3. **Validity Check**\
   The ZDNS cluster first validates whether the request is a well-formed DNS packet. Only valid requests proceed to the resolution phase.
4. **Domain Resolution**
   * **Miss on private authoritative domains**:\
     The query is forwarded to the public internet for recursive resolution, and the final result is returned.
   * **Hit on a VPC private authoritative domain**:
     * **Subdomain match**: Resolve and return the result directly.
     * **Subdomain miss**:
       * **Recursive enabled**: Forward to public recursive resolution and return the final answer.
       * **Recursive disabled**: Return an empty response.
5. **Response to Client**\
   The final resolution result is sent back to the client, delivering a fast and reliable DNS response.

## Virtual Machine DNS Configuration

Currently, only manual DNS configuration is supported. Automatic default DNS via DHCP will be available in the future.

* **IPv4 Instance Default DNS:** `169.254.169.253`
* **IPv6-only Instance Default DNS:** `fd00:a9fe:a9fd::1`

### **CentOS (including CentOS 7/9)**

#### **1. Temporary Configuration**

Edit `/etc/resolv.conf`:

```bash
sudo vim /etc/resolv.conf
```

Add:

```
nameserver 169.254.169.253
```

Save and exit. Changes take effect immediately.

#### **2. Persistent Configuration**

Edit the network interface configuration file `/etc/sysconfig/network-scripts/ifcfg-eth0`:

```bash
sudo vim /etc/sysconfig/network-scripts/ifcfg-eth0
```

Add:

```
DNS1=169.254.169.253
PEERDNS=no
```

Example default file:

```
# Created by cloud-init on instance boot automatically, do not edit.
BOOTPROTO=dhcp
DEVICE=eth0
DHCPV6C=yes
IPV6INIT=yes
ONBOOT=yes
STARTMODE=auto
TYPE=Ethernet
USERCTL=no
DNS1=169.254.169.253
PEERDNS=no
```

#### **3. Verification**

Run:

```bash
sudo cat /etc/resolv.conf
```

Expected output:

```
nameserver 169.254.169.253
```

***

### **Ubuntu (including 20.04/22.04/24.04)**

#### **1. Configuration (Recommended: Netplan)**

Edit the network config file `/etc/sysconfig/network-scripts/ifcfg-eth0`:

```bash
sudo vim /etc/netplan/50-cloud-init.yaml
```

Add:

```yaml
dhcp4-overrides:
    use-dns: false
dhcp6-overrides:
    use-dns: false
nameservers:
    addresses:
      - 169.254.169.253
```

Complete example (replace with actual MAC address):

```yaml
# This file is generated from information provided by the datasource.  Changes
# to it will not persist across an instance reboot.  To disable cloud-init's
# network configuration capabilities, write a file
# /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following:
# network: {config: disabled}
network:
    version: 2
    ethernets:
        eth0:
            dhcp4: true
            match:
                macaddress: 52:54:00:8d:a7:d3
            set-name: eth0
            dhcp4-overrides:
                use-dns: false
            dhcp6-overrides:
                use-dns: false
            nameservers:
                addresses:
                  - 169.254.169.253
```

#### **2. Apply Network Changes**

```bash
sudo netplan apply
```

#### **3. Verification**

Ru&#x6E;**:**

```bash
sudo resolvectl
```

Expected output:

```
DNS Servers: 169.254.169.253
```