Skip to content
Cloudflare Docs
DirectoryAPISDKsChangelog

High availability

For production deployments, you can run multiple replicas of a Mesh node in active-passive mode. All replicas share the same node identity and advertise the same routes. If the active replica goes down, Cloudflare automatically promotes a standby replica.

When to use high availability

High availability provides resilience for CIDR route prefixes advertised by a Mesh node. When the active replica disconnects, Cloudflare promotes a standby so that traffic to the advertised subnets continues to flow.

This means HA is useful for nodes that have routes configured — nodes acting as subnet gateways for private networks behind them. If a node is only used for direct Mesh IP connectivity (no routes), HA has limited benefit because the node's Mesh IP is tied to the individual replica.

How it works

When you create a Mesh node with high availability enabled, Cloudflare generates a single token for that node. You install the Cloudflare One Client on multiple Linux hosts using this token. Each host registers as a replica of the same node.

  • All replicas advertise the same CIDR routes.
  • One replica is active at a time. The others are passive standby.
  • If the active replica disconnects, Cloudflare automatically promotes a passive replica.
  • Failover is handled by Cloudflare's network.
flowchart LR
  subgraph replicas["Mesh node: web-server"]
    R1["Replica 1 <br> (active)"]
    R2["Replica 2 <br> (standby)"]
    R3["Replica 3 <br> (standby)"]
  end
  CF((Cloudflare)) <--> R1
  CF -. failover .-> R2
  CF -. failover .-> R3
  client["Client device"] <--> CF

Create a node with high availability

When you create a Mesh node through the dashboard, high availability is enabled by default. To create a new node:

  1. In the Cloudflare dashboard, go to Networking > Mesh.

    Go to Mesh

  2. Select Add a node.

  3. Follow the setup wizard. The node is created with HA enabled automatically.

  4. Copy the install commands and run them on your Linux host.

Add replicas

To add a replica to an existing high-availability node, install the Cloudflare One Client on a new Linux host and register it using the same node token.

  1. In the Cloudflare dashboard, go to Networking > Mesh.

    Go to Mesh

  2. Select your Mesh node.

  3. Select Add a replica.

  4. A dialog shows the install commands and the node's token.

  5. On a new Linux host, run the install commands shown in the dialog.

Installation commands
Terminal window
curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg &&
echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list &&
sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp &&
printf 'net.ipv4.ip_forward = 1\nnet.ipv6.conf.all.forwarding = 1\nnet.ipv6.conf.all.accept_ra = 2\n' | sudo tee /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf &&
sudo sysctl --system
Terminal window
sudo warp-cli connector new <TOKEN> && sudo warp-cli connect

The new replica will be in standby mode until the active replica disconnects.

View replicas

  1. In the Cloudflare dashboard, go to Networking > Mesh.

    Go to Mesh

  2. Select an HA-enabled node. HA nodes display an HA badge in the overview table.

  3. The node detail page shows a tab for each replica. Each tab displays:

    • Active or Passive badge
    • Mesh IP (IPv4 and IPv6)
    • Edge data center
    • Origin IP
    • Platform, version, and device name
    • Connected since timestamp

Manual failover

In addition to automatic failover when the active replica disconnects, you can manually promote a passive replica to active.

  1. In the Cloudflare dashboard, go to Networking > Mesh.

    Go to Mesh

  2. Select an HA-enabled node.

  3. Select the tab for the passive replica you want to promote.

  4. Select Promote to active.

  5. In the confirmation dialog, select Promote to active to confirm.

Traffic reroutes to the promoted replica immediately. The previous active replica switches to passive standby.

Considerations

Setup requirements

  • High availability is set at node creation time and cannot be changed afterward.
  • You must install the client on at least two hosts for failover to work. A single replica means no redundancy.
  • High availability requires the MASQUE transport protocol. WireGuard does not support HA. Mesh nodes use MASQUE by default.

Network configuration

  • All replicas must be on the same subnet and have the same network routing configuration (Split Tunnels, static routes).
  • HA provides resilience for CIDR route prefixes. Nodes without routes do not benefit from HA failover.

Failover behavior

  • Failover time depends on how quickly Cloudflare detects the active replica has disconnected (typically seconds).
  • Inbound traffic (from Mesh clients to the subnet) fails over automatically on Cloudflare's network. Cloudflare routes traffic to the newly promoted active replica.
  • Outbound traffic (from devices on the subnet through the Mesh node) does not fail over automatically. Your environment must detect that a different replica has been promoted to active and update routing tables to send traffic through the now-active host. There is no client-side failover for on-ramp traffic at this time.