DNS steering and alerts

ConceptsCopy Anchor Link

Configure DNS steeringCopy Anchor Link

DNS steering writes steering records for each cluster; the CNAME targets of sites and L4 apps point at the healthy nodes of their cluster. Edgeweir does not run an authoritative DNS server; it manages records through each provider's API.

Add a provider accountCopy Anchor Link

1. Open DNS steering and click Add provider account.
2. Fill in Name, select DNS provider, and fill in the credential fields the form shows (fields and required permissions: Providers and credentials).
3. For providers that can list zones, click List zones and pick the Zone; otherwise type the Zone.
4. Click Test connection. Verify: Connected: N records in the zone appears.
5. Click Create. Saving first runs the same test as Test connection; when it fails, the dialog shows the error and the button becomes Save anyway.

An account is one set of credentials and one zone; for several zones under the same credentials, add one account per zone. Test connection in the account list reads the zone with the saved credentials. Edit renames the account; turn on Replace credentials and fill in every field again to rotate secrets, which are tested before saving too. A rename alone is not tested. After a failed test, changing any field makes the next save test again. The provider and zone cannot change after creation. Credentials are envelope-encrypted with the master key and are write-only.

Bind a clusterCopy Anchor Link

1. Open Clusters & nodes, select the cluster, and switch to the DNS tab (shown once the cluster has a node).

2. Select Mode: Not managed, Manual, or Automatic.

3. Select Provider account; Zone shows the account's zone. Fill in Cluster domain and TTL (seconds).

4. If needed, click Add line, fill in Line name, and select a Node group of this cluster; if needed, select a Resolution line, fill in Minimum healthy IPs, and use Add backup group under Backup node groups, ordering the groups. For a node behind NAT or on a private network, enter its public addresses in the node's node name: target addresses field, or configure the node's scheduling addresses; leave it empty to use the node's scheduling addresses. Without lines, all.<cluster domain> answers with the addresses of every healthy node of the cluster.

5. Click Save. The console shows DNS revision N created.

6. Verify: the Current records card shows Published, and the site's Domains tab shows the CNAME target.

   Copy Text

   dig +short CNAME <site UUID>.<cluster domain>
   dig +short A all.<cluster domain>

   The first prints all.<cluster domain>., the second the addresses of the cluster's healthy nodes.

7. In each site domain's DNS, CNAME the domain to the CNAME target. Below it the card lists where each domain resolves (Points here, Points elsewhere, Not resolved, Not checked); the Launch check on the site's Overview tab sums it up as DNS pointed N/M.

Clusters may use different provider accounts and cluster domains. The Cluster bindings table on the DNS steering page lists each cluster's mode, cluster domain, and publication state; Open goes to the cluster's DNS tab.

Binding fieldsCopy Anchor Link

A binding has at most 128 lines and 10,000 system-managed records. Two bindings with the same cluster domain in the same zone cannot share line names or the all-lines record name (DNS_BINDING_CONFLICT).

With a provider that has the default line only, Resolution line is unavailable and shows This provider has only the default line; selecting an account whose provider lacks a resolution line moves those lines back to default in the form. Saving a resolution line the provider does not support returns DNS_LINE_UNSUPPORTED ("This DNS provider has no {line} resolution line"). Manual mode without a provider account can use every resolution line.

Generated recordsCopy Anchor Link

Address records are written once per cluster (all.<cluster domain> once per resolution line in use): the record count is "sites + enabled L4 apps + cluster addresses", plus "(sites + enabled L4 apps) × lines" with per-site line targets. With per-site line targets off, the line targets on a site's Domains tab and on an L4 app's page are <line name>.<cluster domain>.

The Resolution line column of the Current records and Records to create tables shows each record's resolution line.

Records per resolution lineCopy Anchor Link

all.<cluster domain> has one record set on every resolution line in use; every other record is on the default line only.

• Resolvers no other resolution line matches get the default line's records; DNSPod requires a record on the default line.
• Writing a name and type replaces its records on every resolution line; copies on resolution lines no longer in use are deleted. A binding that uses the default line only writes the same records as before.
• Records on a resolution line the account's provider no longer supports are not written.

Example:

all.<cluster domain> answers China Telecom users with the addresses of telecom-nodes, China Unicom users with those of unicom-nodes, and everyone else with those of overseas-nodes. Without intl, the default line answers with every address of ct and cu.

Backup node groupsCopy Anchor Link

A node group may back up several lines, but not its own line.

Manual modeCopy Anchor Link

The console writes no DNS. The cluster's DNS tab lists the records to create (absolute names) and a BIND zone file; Download saves it as <zone>.zone.

Upgrading from the global DNS configurationCopy Anchor Link

Earlier versions had one global DNS steering configuration. On upgrade it becomes one binding per cluster, and the CNAME records of site domains need no change:

• Every cluster's cluster domain is the former CNAME domain, so each site's CNAME target keeps its name and resolves to the same addresses as before.
• A configuration that was on becomes Automatic with Keep per-site line targets on, so the line targets a site's Domains tab listed, <line>.<site UUID>.<CNAME domain>, keep resolving; one that was off becomes Not managed, with account, domain, and lines kept in the form.
• When several clusters share the former CNAME domain, their all-lines records are named all, all-2, … (clusters with sites first) and each site's CNAME points at its cluster's record.
• The former per-site address records all.<site UUID>.<CNAME domain> are removed by the next reconciliation, which deletes only names the console registered.
• If the first publication after the upgrade would leave only CNAMEs and no address records (for example before any node has reconnected), the cluster keeps its previous records and the revision shows Held back, as in Mass removal protection; it continues once nodes are back, or with Publish anyway.
• Earlier DNS revisions stay in the database and are no longer shown.
• In /api/v1, /dns/config, /dns/revisions, and /dns/force-publish become the per-cluster /clusters/{clusterId}/dns, /clusters/{clusterId}/dns/revisions, and /clusters/{clusterId}/dns/force-publish; /dns/bindings lists every cluster's binding.

Health removal and repairCopy Anchor Link

A failed DNS revision shows its reason: provider authentication failed, zone not found at the provider, provider unreachable, provider rate limit, a name has unmanaged records, a name belongs to another cluster, server address refused by the outbound policy, and so on.

Mass removal protectionCopy Anchor Link

When a publication would empty a cluster's previously non-empty all. or line record set (each resolution line counted separately), or remove more address records than the threshold allows, the cluster's previous records stay and nothing is written to the provider. The same applies when the console loses its node channel and every node looks offline.

DNS revisions and rollbackCopy Anchor Link

Each cluster has its own DNS revisions, which do not advance the node configuration revision. Roll back DNS restores the binding settings of the chosen revision (mode, account, cluster domain, TTL, lines with their resolution lines, backup node groups, and minimum healthy IPs); addresses are still computed from the current sites and node health, so offline nodes are not restored. Manual-mode revisions are Published as soon as they are saved. Each cluster keeps its latest 200 DNS revisions; the current, published, and Blocked revisions are never pruned.

The Reason column of the DNS revisions table:

Before deleting a provider account, point the clusters that use it at another account or switch them to Not managed and wait for cleanup (the account no longer owns system-managed records); otherwise the console returns DNS_PROVIDER_IN_USE. Likewise, before deleting a cluster, switch its DNS to Not managed and wait for cleanup (DNS_BINDING_IN_USE).

Providers and credentialsCopy Anchor Link

DNS steering provider accounts and the DNS credentials used for certificate DNS-01 (see HTTPS and certificates) use the same provider catalog and forms. Give credentials the least permission the zone needs.

Each provider adapter is tested only with recorded API exchanges (requests and answers built from the provider's official API reference); none has been accepted against a real account. Use Test connection before relying on one.

Apex: CNAME flattening or an ALIAS record lets the zone apex (@) point at a host name (such as a site's CNAME target); with other providers the apex can only use A / AAAA records. For resolution lines see Resolution lines; the carrier or regional lines of other providers (offered by Volcengine, Baidu AI Cloud, West.cn, DNS.LA, Route 53, Google Cloud DNS, Gcore, and Bunny DNS) are not used, and records go to the default line.

Providers not supported:

Resolution linesCopy Anchor Link

Resolution lines let one name answer differently by carrier or region. The provider adapters use the line names below and translate them to each provider's own lines:

• Only these four providers (Tencent Cloud DNSPod on both the China and the international site) support every line; other providers have default only and refuse records on other lines. capabilities.lines in GET /dns/catalog lists each provider's lines.
• Writing a name and type replaces its records on every line: copies on lines missing from the write are deleted.
• When reading, provider lines outside the table (such as province lines) show as other:<provider line>; such records can only be deleted. Alibaba Cloud is read line by line for the lines in the table, so records on other lines may not be read.

Self-hosted endpoints and the outbound policyCopy Anchor Link

The addresses of PowerDNS, RFC 2136, and Custom HTTP are entered by the operator, so every connection goes through the outbound address policy:

Custom HTTP protocolCopy Anchor Link

Every operation is one request:

POST <URL>
Content-Type: application/json
User-Agent: edgeweir-certd/1
X-Edgeweir-Timestamp: <Unix seconds>
X-Edgeweir-Signature: v1=<hex>

<hex> is the lowercase hexadecimal HMAC-SHA256, keyed with the signing secret, of the timestamp, ., and the raw request body. Receivers recompute it over the raw body, compare in constant time, and answer 401 to a wrong signature or a timestamp more than 300 seconds away from their clock. Example: secret example-secret-0123456789, timestamp 1700000000, and body {"action":"zones"} give v1=3af007dacbb4d9b54c57bc499f275d13e48a5513e8ecf036d83c1b5a6c0f20f8.

Body:

{"action":"set","zone":"example.com","records":[{"name":"www","type":"A","data":"192.0.2.1","ttl":600}]}

A success is a 2xx JSON answer (up to 16 MiB): {"records":[...]} for list, append, set, and delete; {"zones":["example.com"]} for zones. 401 or 403 means authentication failed, 404 an unknown zone, 501 on zones that the receiver cannot list zones; 429 is treated as rate limiting and 5xx as unavailable. Error answers may carry {"error":"short text"}. The signature covers only a timestamp, so a request can be replayed within 300 seconds: set and delete are idempotent, append needs deduplication by the receiver.

Alerts pageCopy Anchor Link

Alerts are configured on the Alerts page, which has five cards:

Configure alert channelsCopy Anchor Link

1. Open Alerts and click Add channel in the Alert channels card.
2. Enter Name, select Channel type, and fill in the fields for that type (see below).
3. Select Notification language.
4. Turn on Receive every alert as needed.
5. Click Create.
6. Verify: click Send test; the target receives a test notification and the channel row does not show Notification delivery failed.

Email channels use the server in the SMTP card, see SMTP.

Channel fieldsCopy Anchor Link

Channels without this switch receive only the site alerts subscribed to them, see Subscribe to alerts.

At most 32 channels. When editing a channel, turn on Replace channel credentials to re-enter the type and fields; otherwise the stored credentials are kept. A disabled channel sends no notifications and cannot be chosen for new subscriptions.

Webhook payloadCopy Anchor Link

The request body is JSON with id (event ID), siteId, siteName, kind, status (firing / resolved), occurredAt, resourceId (the object of the alert, such as a node or certificate ID), text, and url (a console link). For cluster and DNS alerts, siteId is null and siteName is the cluster name; for Node offline, siteId is null, siteName is the node name and resourceId the node ID; and url points to Clusters & nodes or DNS steering; for scheduling_action, siteName is "rule · node" and resourceId is <rule ID>:<node ID>. With a bearer token, the request carries Authorization: Bearer <token>. A 2xx response counts as delivered.

SMTPCopy Anchor Link

The outgoing mail server of email channels, set in the SMTP card of the Alerts page and saved with Save. Until it is set, Send test on an email channel answers "SMTP is not configured", and a channel whose deliveries fail for that reason shows the same message.

Set alert rulesCopy Anchor Link

1. Open Alerts and change the thresholds in the Alert rules card.
2. Click Save.

Origin unavailable has no threshold of its own: it fires when one node reports, within the offline threshold, every origin of the site unavailable. An origin is unavailable on that node when its passive or its active check result (either source) is unhealthy; see Passive health check and Active health check.

CC mitigation raised (cc_mitigation) has no threshold of its own: it fires when a node reports that the site left the normal level, at most once per site in 15 minutes (a raise held back fires at the next minute check once the 15 minutes are over, if the site is still above normal), and resolves once no online node reports the site above normal. See Challenges and CC mitigation.

Site alerts cover only enabled sites with at least one domain.

Cluster and DNS alertsCopy Anchor Link

These alerts belong to a cluster, not to a site. They go only to channels with Receive every alert and cannot be subscribed to; Recent events lists them too.

Subscribe to alertsCopy Anchor Link

1. Open Alerts and click Subscribe in the Subscriptions card.
2. Select Notification channel.
3. Turn on All sites, or tick sites in the Sites list (Search sites finds them; ticked sites stay ticked across searches).
4. Turn on the alert kinds to send and click Save.
5. Verify: the subscription row shows the channel, the sites (or All sites), and the alert kinds; Recent events shows these sites' events.

Delivery behaviorCopy Anchor Link

LimitsCopy Anchor Link

TroubleshootingCopy Anchor Link