Skip to content
actor-ts

DNS seed provider

DnsSeedProvider resolves seeds via DNS at startup. Two modes:

ModeLookupResult
SRV records_actor-ts._tcp.example.comService + port from records
A recordsactor-ts.example.comIPs only; port comes from config

SRV is the more flexible choice (service-discovery-style); A records work for simpler setups.

import { Cluster, DnsSeedProvider } from 'actor-ts';


const provider = new DnsSeedProvider({
  service:   '_actor-ts._tcp.example.com',
});


const seeds = await provider.lookup();
await Cluster.join(system, { host, port, seeds });

Configuration

Section titled “Configuration”
interface DnsSeedProviderSettings {
  service:    string;     // SRV record (or A-record hostname)
  port?:      number;     // required for A-record mode
  resolver?:  DnsResolver; // override default Node DNS
}
Section titled “SRV mode (recommended)”
new DnsSeedProvider({ service: '_actor-ts._tcp.my-app.example.com' });

SRV records carry host, port, weight, priority per entry. The provider returns host:port for every entry the DNS query returned.

To create the SRV records:

_actor-ts._tcp.my-app.example.com.   IN SRV  10 100 2552 node-1.my-app.example.com.
_actor-ts._tcp.my-app.example.com.   IN SRV  10 100 2552 node-2.my-app.example.com.
_actor-ts._tcp.my-app.example.com.   IN SRV  10 100 2552 node-3.my-app.example.com.

Plus matching A records for the hostnames. Most DNS-SD service-registration tools (Consul, Eureka with DNS plugin) publish SRV records automatically.

A-record mode

Section titled “A-record mode”
new DnsSeedProvider({
  service: 'actor-ts.example.com',
  port:    2552,
});

For setups without SRV — DNS only carries IPs. The provider queries A records and pairs each with the configured port.

A records typically point at a load balancer or a round-robin DNS list; multiple A entries mean multiple seed candidates.

When to use it

Section titled “When to use it”
EnvironmentUse
Consul-managed deploymentsSRV mode — Consul writes them automatically.
Eureka with DNS pluginSRV mode.
Manual deployments with DNS serverEither mode; SRV preferred.
Cloud with DNS-based service discoverySRV mode.
K8sUse KubernetesApiSeedProvider — K8s’s headless services do produce A records but the K8s API provider is more reliable.

DNS caching

Section titled “DNS caching”
// The provider does ONE lookup at startup.  No subsequent refresh.

Once Cluster.join completes, the cluster’s gossip layer takes over membership tracking — DNS is no longer consulted. This means:

  • A node added after startup isn’t visible to existing peers via DNS. It joins via its own DNS lookup, contacts an existing seed, gossip propagates.
  • DNS TTLs don’t matter for the cluster’s runtime — only at startup.

When NOT

Section titled “When NOT”

Where to next

Section titled “Where to next”