Kea DHCP High Availability: Hot-Standby Cluster Setup

An ISC DHCP server pair with failover has been the standard design for a decade, but ISC
DHCP is deprecated and Kea is the supported replacement. Kea implements HA differently: instead
of the peer protocol in the DHCP daemon, HA is a hook library that speaks HTTPS between two Kea
servers, with hot-standby and load-balancing modes. This article builds a two-node hot-standby
pair, explains what the standby node does while the primary is healthy, and shows how to prove
the pair is synchronised before you rely on it.

Design: What Hot-Standby Gives You

• Primary — answers all DHCP traffic.
• Standby — answers nothing while the primary is healthy, but holds a
  synchronised lease database so it can take over in seconds.
• Communication — HTTPS between the two servers on port 8000 by convention.
  Both nodes must be able to reach each other on that port; a firewall between them is the first
  thing to check when HA shows as partner-down permanently.

Kea's HA model deliberately does not include pool rebalancing the way ISC DHCP failover did.
That is a documented difference and worth knowing before you design around it: in Kea you scale
by adding subnets or servers, not by having the pair split pools.

Step 1: Install the HA Hook

apt install isc-kea-dhcp4-server isc-kea-hooks
ls /usr/lib/x86_64-linux-gnu/kea/hooks/
#   libdhcp_ha.so
#   libdhcp_lease_cmds.so

libdhcp_lease_cmds.so is required alongside libdhcp_ha.so: the
lease commands hook backs the control channel Kea uses to query and synchronise leases.

Step 2: Primary Server Configuration

{
  "Dhcp4": {
    "interfaces-config": { "interfaces": [ "ens192" ] },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "/var/lib/kea/kea-leases4.csv",
      "lfc-interval": 3600
    },
    "valid-lifetime": 28800,
    "option-data": [
      { "name": "domain-name-servers", "data": "10.10.1.10, 10.10.1.11" }
    ],
    "hooks-libraries": [
      { "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so" },
      {
        "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
        "parameters": {
          "high-availability": [ {
            "this-server-name": "kea1",
            "mode": "hot-standby",
            "heartbeat-delay": 10000,
            "max-response-delay": 30000,
            "max-ack-delay": 5000,
            "max-unacked-clients": 5,
            "peers": [
              { "name": "kea1", "url": "http://10.10.1.10:8000/", "role": "primary" },
              { "name": "kea2", "url": "http://10.10.1.11:8000/", "role": "standby" }
            ]
          } ]
        }
      }
    ],
    "subnet4": [ {
      "subnet": "10.10.20.0/24",
      "id": 1,
      "option-data": [ { "name": "routers", "data": "10.10.20.1" } ],
      "pools": [ { "pool": "10.10.20.10 - 10.10.20.249" } ]
    } ],
    "loggers": [ {
      "name": "kea-dhcp4",
      "severity": "INFO",
      "output_options": [ { "output": "/var/log/kea/kea-dhcp4.log" } ]
    } ]
  }
}

Step 3: Standby Server Configuration

The standby configuration is identical except for three values — the server's own name
changes, and the roles stay as defined on both sides:

"this-server-name": "kea2",
"peers": [
  { "name": "kea1", "url": "http://10.10.1.10:8000/", "role": "primary" },
  { "name": "kea2", "url": "http://10.10.1.11:8000/", "role": "standby" }
]

Both nodes must list both peers with identical roles. If the roles differ between the two
configurations, the HA state machine will not converge.

Step 4: Start, Then Verify

# Enable the control socket for the HA commands
#   "control-socket": { "socket-type": "unix", "socket-name": "/tmp/kea-dhcp4-socket" }

systemctl restart isc-kea-dhcp4-server

# Ask for the HA state
kea-shell --host 127.0.0.1 --port 8000 --path / --timeout 10 <<'EOF'
{
  "command": "ha-heartbeat",
  "service": [ "dhcp4" ]
}
EOF

kea-shell --host 127.0.0.1 --port 8000 --path / --timeout 10 <<'EOF'
{ "command": "ha-status", "service": [ "dhcp4" ] }
EOF

Expected state on a healthy pair: hot-standby on the primary and
hot-standby on the standby, with DHCP startup complete messages in
both logs. Anything else — partner-down, waiting,
syncing — points at the peer URL, the TLS/HTTP transport, or an initial
synchronisation that has not finished.

Failover and Failback

The standby detects a dead peer after max-response-delay and starts serving.
That window is the real recovery objective — size it deliberately, because a value that is too
short causes unnecessary flapping during a brief network blip. When the primary returns, the
pair enters syncing and the standby gives the primary an updated lease set before
returning to standby. Watch both logs during the first failback; that is where configuration
drift between the nodes shows up.

# Useful records of what happened
grep -i "ha\|partner\|sync" /var/log/kea/kea-dhcp4.log
journalctl -u isc-kea-dhcp4-server --since "1 hour ago"

Operational Checklist

• Both nodes must run the same Kea version and the same subnet definitions. Diff the
  configurations as a scheduled job, not by eye.
• Keep the lease file on local storage that survives reboot, and enable LFC so the memfile
  backend compacts rather than grows forever.
• Monitor the HA state as a first-class metric; a pair silently stuck in
  partner-down is worse than a single server because it looks redundant.
• Kea handles client classes, option 82 and vendor-specific options well — but if you
  forward relayed requests, verify the relay path. See DHCP Option 82 and IP Source Guard for the access-layer side and Arista EOS ZTP with DHCP Option 67 for a DHCP-driven provisioning use case.
• If you need a virtual IP in front of the pair, Keepalived VRRP and HAProxy virtual IP failover covers the addressing layer.

原文链接：https://kb.isc.org/docs/kea-ha-quickstart-guide