Clustering Requirements
Hosts, networking, and DNS delegation needed before deploying a Pangolin cluster
Clustering is only available in Enterprise Edition.
Review these requirements before you start deploying. They cover the hosts you need, the ports that must be open, and the DNS records you need to delegate ahead of time. For background on why each piece exists, see Understanding Clustering.
Hosts
You need a minimum of three hosts:
- Node 1 - runs Pangolin, Gerbil, and Traefik
- Node 2 - runs Pangolin, Gerbil, and Traefik
- A database host - runs PostgreSQL and a Redis-compatible server (Valkey, Redis, etc.)
The database host doesn't need to be a dedicated instance. You can run PostgreSQL and Redis however you like - a managed cloud database, an existing cluster, etc. - as long as both nodes can reach them. The only hard requirement is that the Redis-compatible server supports pub/sub.
You can add more Pangolin nodes beyond two for additional capacity or regional distribution. The two-node topology in this guide is the minimum for high availability.
For sizing information, see Choosing a VPS - the same sizing from single Pangolin node deployments applies to each node in a cluster.
Networking
- Node 1 and Node 2 each need a public, static IP address, reachable from the internet
- Node 1 and Node 2 need to be able to address each other over an internal network
- You must provide your own HA load balancer in front of both nodes. It needs to terminate HTTPS for the Pangolin UI and accept UDP port 53 for DNS and route to both nodes
Dashboard Domain
You also need a domain for the Pangolin UI and API itself (e.g. pangolin.example.com) - this is separate from the nameserver domain above, which is the nameserver to resolve resource DNS.
Point this domain's DNS record at your load balancer, not at either node directly. The load balancer is also responsible for obtaining and serving the TLS certificate for this domain - the nodes' built-in ACME client only issues certificates for resource domains under the delegated nameserver zone, not for the dashboard domain. Terminate TLS at the load balancer and forward plain HTTP to the nodes.
You must also set this domain as app.dashboard_url and add it to server.cors.origins in every node's config.yml. See Deploy a Cluster.
Required Ports
Configure the following firewall rules on each Pangolin node.
Inbound
| Type | Protocol | Port range | Source | Description |
|---|---|---|---|---|
| HTTP | TCP | 80 | 0.0.0.0/0 | Ping and redirects |
| HTTPS | TCP | 443 | 0.0.0.0/0 | Pangolin public resources |
| Custom UDP | UDP | 21820 | 0.0.0.0/0 | WireGuard relay port |
| Custom UDP | UDP | 51820 | 0.0.0.0/0 | WireGuard port |
| DNS (UDP) | UDP | 53 | Load balancer | DNS |
| HTTP | TCP | 3000 | Load balancer | Pangolin dashboard UI and API |
| Custom TCP | TCP | 3004 | Self + all other nodes | Gerbil node API |
Outbound
| Type | Protocol | Port range | Destination | Description |
|---|---|---|---|---|
| All traffic | All | All | 0.0.0.0/0 | Allow all outbound |
DNS Delegation
Pangolin's built-in DNS server needs to be delegated authority for a nameserver subdomain. Point an NS record at your load balancer, then optionally delegate additional subdomains through it.
Create the nameserver record
Create an A record pointing your chosen nameserver hostname at your load balancer's IP. The examples in this guide use ns.example.com - substitute your own domain or subdomain.
| Name | Type | Value |
|---|---|---|
ns.example.com | A | <LOAD_BALANCER_IP> |
Delegate CNAME-based domains (optional)
If you want to support CNAME delegation for resource domains, delegate a subdomain to your nameserver.
| Name | Type | Value |
|---|---|---|
cname.example.com | NS | ns.example.com |
Delegate site-to-cloud resolution (optional)
If you want to support site-to-cloud networking - resolving a site's tunnel address by DNS from within a cloud environment - delegate another subdomain the same way.
| Name | Type | Value |
|---|---|---|
site.example.com | NS | ns.example.com |
These three hostnames map directly to the dns section of privateConfig.yml, covered in Deploy a Cluster:
dns:
enabled: true
nameserver_name: "ns.example.com"
cname_extension: "cname.example.com"
site_extension: "site.example.com" # OptionalOther Requirements
- Contact email for Let's Encrypt ACME registration
- GeoIP databases - download and keep up to date the MaxMind
GeoLite2-Country.mmdbandGeoLite2-ASN.mmdbdatabases, placed in each node'sconfig/directory. See Enable Geo-location and Enable ASN Lookup - Site type support - in clustered deployments, only Pangolin Sites are supported. Local sites and basic WireGuard sites are not supported
Was this page helpful?