DNS Setup

A very common scenario is that you want to reach a service running on your Avassa edge site by its name. By default, the ingress addresses of ready applications are added to DNS. However, because most sites are on a private network, name resolution rarely works without some additional network configuration.

This tutorial describes how to configure DNS so that devices on your network can resolve the names of services running on Avassa edge sites. It covers several common network configurations, from a large corporate network with many sites down to a small isolated site.

Before reading this, you should be familiar with the Avassa DNS concepts in DNS, in particular how the Edge Enforcer acts as an authoritative name server for the site domain, and how ingress IP addresses are registered in DNS.

This tutorial assumes you are comfortable with DNS concepts such as nameservers, the difference between recursive resolvers and authoritative nameservers, forward zones, and delegation.

DNS names and certificates

One of the reasons to reach services by name rather than by IP address is TLS certificate verification. Avassa's Control Tower can act as a certificate authority (CA) for services running on your edge sites. Devices that install the Control Tower CA certificate can then verify the authenticity of any service on any edge site over HTTPS (including the Server Name Indication, which typically is the DNS name).

For a practical example of setting this up, see Request certificates in application specifications.

Naming conventions used in this document

The examples below use the following values consistently:

Thing	Example value
Avassa environment (global DNS domain)	prod.example.avassa.net
Tenant	acme
Sites	blue, green, red
Sample application	inventory
Customer-owned domain	example.com
Custom zone per site	blue.edge.example.com etc.

For the sake of this example we will assume that the inventory application is configured with ingress-ip-per-instance, with mode: replicated and replicas: 2 (i.e. it will request an ingress address for each instance, and it will run in two instances on each site). The sample ingress addresses will be .40 and .41 in each site's subnet.

Sites differ in size to illustrate that a site can have one or many hosts:

Site	Hosts	Edge Enforcer IP addresses
blue	3	10.10.10.1, 10.10.10.2, 10.10.10.3
green	1	10.20.10.1
red	1	10.30.10.1

Each host in a site runs its own Edge Enforcer, which includes its own DNS nameserver. Forwarding rules and DHCP nameserver lists should include all hosts in a site so that DNS resolution continues if any one host is unavailable.

Each site has a domain of the form <site>.site.<global-domain>. For example:

blue.site.prod.example.avassa.net

Application records are registered under a tenant subdomain within that:

<service>-<n>.<application>.<tenant>.<site>.site.<global-domain>

For example, the inventory application's instances for tenant acme on site blue:

inventory-1.inventory.acme.blue.site.prod.example.avassa.net
inventory-2.inventory.acme.blue.site.prod.example.avassa.net
inventory.inventory.acme.blue.site.prod.example.avassa.net  - round-robin of ready instances

Because a site can serve multiple tenants, delegation and forwarding should target the site-level domain (blue.site.prod.example.avassa.net), not a tenant subdomain.

---

Choosing an approach

Scenario	Use when
1a. Avassa built-in domain	Corporate network; sites have public IPs, or your resolver supports per-domain private-address exceptions
1b. Direct forwarding	Corporate network; sites have private IPs and you want to avoid touching resolver policy
1c. Custom domain	Corporate network; you want short, branded names (e.g. inventory.blue.edge.example.com)
2a. Existing nameserver	Standalone site with a pre-existing local nameserver
2b. Edge Enforcer as nameserver	Standalone site with no pre-existing nameserver - simplest possible setup

The scenarios are grouped by network type. Corporate network (1a–1c): many sites on a shared private WAN managed by a central IT team — using the Edge Enforcer as the resolver for corporate devices is not an option. Standalone site (2a–2b): a single site on its own isolated local network with no connection to a corporate WAN.

---

Scenario 1: Sites on a corporate network

In this scenario, many sites—potentially tens to hundreds—are all connected to the same corporate private network. A central IT team manages one or more nameservers used by all devices across the network.

The goal is that any device on the corporate network can resolve the names of services running on any site. There are three approaches.

1a. Avassa built-in domain

Avassa automatically maintains the DNS delegation for the environment domain (prod.example.avassa.net). A resolver that can reach Avassa's public authoritative nameservers will follow the delegation chain and eventually reach the Edge Enforcer host that holds the answer.

The private address problem

Sites on a corporate private network typically have RFC 1918 addresses. When a resolver follows the standard delegation chain and receives a response from a public Avassa nameserver containing a private IP address, some resolvers will discard that address as a protection against DNS rebinding attacks. The lookup fails even though the delegation is technically correct. Whether or not to allow delegation with RFC 1918 addresses is typically a policy decision and most likely requires configuration of the nameservers.

For example: in unbound, private address filtering is controlled by the private-address directive. It is not enabled by default, but when it is configured, you can add a targeted per-domain exception using private-domain. This tells unbound to allow RFC 1918 addresses in responses for a specific domain and all its subdomains, while leaving the filter in place for everything else:

server:
    private-address: 10.0.0.0/8
    private-address: 172.16.0.0/12
    private-address: 192.168.0.0/16
    private-domain: "site.prod.example.avassa.net"

If your resolver already has private-address configured, you only need to add the private-domain line.

Other resolvers may have similar or different mechanisms for controlling private address handling; check your resolver's documentation.

When this works well: your sites have public IP addresses, or your resolver either does not filter private addresses or supports a per-domain exception like the one above.

No Avassa-side configuration is required; the delegation is maintained automatically.

If the private-address problem applies and your resolver does not support a per-domain exception, see 1b, which bypasses the delegation chain entirely.

1b. Direct forwarding from corporate DNS

Instead of relying on the public delegation chain, the corporate nameserver is configured with a per-site conditional forwarder that points queries for the site domain directly to the Edge Enforcer hosts. This bypasses the delegation chain entirely and avoids the RFC 1918 problem.

Forward at the site-domain level so that all tenants on the site are covered by a single entry. For each site, add a forward zone to the corporate nameserver:

Unbound:

forward-zone:
    name: "blue.site.prod.example.avassa.net"
    forward-addr: 10.10.10.1
    forward-addr: 10.10.10.2
    forward-addr: 10.10.10.3

forward-zone:
    name: "green.site.prod.example.avassa.net"
    forward-addr: 10.20.10.1

forward-zone:
    name: "red.site.prod.example.avassa.net"
    forward-addr: 10.30.10.1

BIND:

zone "blue.site.prod.example.avassa.net" {
    type forward;
    forward only;
    forwarders { 10.10.10.1; 10.10.10.2; 10.10.10.3; };
};

zone "green.site.prod.example.avassa.net" {
    type forward;
    forward only;
    forwarders { 10.20.10.1; };
};

zone "red.site.prod.example.avassa.net" {
    type forward;
    forward only;
    forwarders { 10.30.10.1; };
};

Windows DNS Server (PowerShell):

Add-DnsServerConditionalForwarderZone -Name "blue.site.prod.example.avassa.net"  -MasterServers 10.10.10.1, 10.10.10.2, 10.10.10.3
Add-DnsServerConditionalForwarderZone -Name "green.site.prod.example.avassa.net" -MasterServers 10.20.10.1
Add-DnsServerConditionalForwarderZone -Name "red.site.prod.example.avassa.net"   -MasterServers 10.30.10.1

No Avassa configuration is required. Each time a new site is added, one more forward zone entry is added to the corporate nameserver.

Trade-off: application configurations reference the full Avassa domain names, which are verbose (e.g. inventory.acme.blue.site.prod.example.avassa.net). If you want shorter, company-branded names, see 1c.

1c. Custom domain

With Avassa's custom domain feature, you can use your own domain (for example example.com) for service names on each site. This gives you clean, branded names and gives IT more targeted control over any private-address configuration.

Avassa configuration

Edit the dns object for the acme tenant in the Control Tower to add a custom zone. Here we name the zone edge and give each site a subdomain under edge.example.com:

zones:
  - name: edge
    domain: ${SYS_SITE}.edge.example.com

With this in place, the Edge Enforcer on each site will consider itself authoritative for its subdomain (blue.edge.example.com, green.edge.example.com, etc.) and install SOA and NS records automatically.

To register application service instances in the custom domain as well as the default Avassa domain, reference it in the application's dns-records configuration:

network:
  ingress-ip-per-instance:
    protocols:
      - name: tcp
        port-ranges: 80,443
    dns-records:
      domains:
        - domain: default
        - domain: ${SYS_DNS_ZONES[edge]}

DNS delegation

For each site, add NS and glue A records in your example.com zone. The glue record provides the IP address of the Edge Enforcer host that will answer queries for the site subdomain:

$ORIGIN example.com.
$TTL 3600

ns1-blue.edge    IN A    10.10.10.1
ns2-blue.edge    IN A    10.10.10.2
ns3-blue.edge    IN A    10.10.10.3
blue.edge        IN NS   ns1-blue.edge.example.com.
blue.edge        IN NS   ns2-blue.edge.example.com.
blue.edge        IN NS   ns3-blue.edge.example.com.

ns1-green.edge   IN A    10.20.10.1
green.edge       IN NS   ns1-green.edge.example.com.

ns1-red.edge     IN A    10.30.10.1
red.edge         IN NS   ns1-red.edge.example.com.

The Edge Enforcer picks up the NS records that the example.com authoritative server has published, and uses them to set its own SOA and NS records. You can verify this with:

% supctl show --site blue dns
zones:
  ...
  - name: edge
    domain: blue.edge.example.com
    records:
      - rr: @ 300 IN NS ns1-blue.edge.example.com.
      - rr: @ 900 IN SOA ns1-blue.edge.example.com. hostmaster.edge.example.com. ...
      - rr: inventory-1 15 IN A 10.10.10.40
      - rr: inventory-2 15 IN A 10.10.10.41
      - rr: inventory 15 IN A 10.10.10.40 10.10.10.41

Once delegation is in place, any device on the corporate network can resolve the inventory service using the custom domain:

• inventory-1.blue.edge.example.com — A record for the ingress address of the first inventory instance
• inventory-2.blue.edge.example.com — A record for the ingress address of the second inventory instance
• inventory.blue.edge.example.com — A record containing the addresses of all ready instances, returned in round-robin order

Each time a new site is added, you add one NS record and one glue A record in your example.com zone. The corporate nameserver requires no per-site configuration—it follows the delegation from example.com normally.

note

If your sites have private IP addresses, the glue A records will contain RFC 1918 addresses. Whether your resolver accepts these depends on its configuration. Because the delegation is within your own domain rather than avassa.net, the exception can be scoped more narrowly—for example private-domain: "edge.example.com" in unbound.

---

Scenario 2: Standalone site

A standalone site is a single Avassa site on its own local network—a branch office, retail location, or industrial facility not connected to a broader corporate WAN. Local devices still need to resolve service names, but there is no shared nameserver infrastructure: either there is no central IT team, or the IT team manages each site location independently.

There are two approaches depending on whether a local nameserver is already present.

2a. Delegating from an existing nameserver

When to use this approach:

• There is already a nameserver on the local network.
• You want local devices to resolve Avassa service names without any device reconfiguration.

Add a forward zone to your existing resolver for the site's domain, pointing to the Edge Enforcer hosts. Forward at the site-domain level to cover all tenants:

Unbound:

forward-zone:
    name: "blue.site.prod.example.avassa.net"
    forward-addr: 10.10.10.1
    forward-addr: 10.10.10.2
    forward-addr: 10.10.10.3

BIND:

zone "blue.site.prod.example.avassa.net" {
    type forward;
    forward only;
    forwarders { 10.10.10.1; 10.10.10.2; 10.10.10.3; };
};

Windows DNS Server (PowerShell):

Add-DnsServerConditionalForwarderZone `
    -Name "blue.site.prod.example.avassa.net" `
    -MasterServers 10.10.10.1, 10.10.10.2, 10.10.10.3

Your resolver will now forward any query for a name under that domain directly to the Edge Enforcer hosts, which will answer authoritatively. Devices do not need any reconfiguration.

2b. Edge Enforcer as local nameserver

When to use this approach:

• There is no pre-existing nameserver on the local network.
• The local devices need to reach a service running on the Edge Enforcer (for example the inventory application).
• You have control over the local DHCP server.

Configure your DHCP server to hand out the Edge Enforcer host addresses as the nameserver for the network. For example, for site blue with three Edge Enforcer hosts:

Kea DHCP (kea-dhcp4.conf, relevant excerpt):

{
  "Dhcp4": {
    "option-data": [
      {
        "name": "domain-name-servers",
        "data": "10.10.10.1, 10.10.10.2, 10.10.10.3"
      }
    ]
  }
}

This sets the nameservers globally for all subnets. The same option-data block can be placed inside a specific subnet4 entry to apply it only to that subnet.

With this in place, any device that receives a DHCP lease will use the Edge Enforcer as its resolver. The Edge Enforcer will answer queries for the site domain authoritatively and forward all other queries to its own upstream nameserver (or it can act as a standalone recursive resolver if no upstream nameserver is available).

note

The Edge Enforcer DNS server only allows devices on locally attached networks to perform recursive lookups. Clients from other addresses can only query the site domain(s) for which it is authoritative.