High Availability

Kaya High Availability is a provider and application resilience framework. It gives supported integrations a shared place to create service clusters, validate nodes, deploy integration-specific protection, keep configuration aligned, monitor health, and manage failover.

Pi-hole is the first supported integration. The initial Beta therefore includes Pi-hole-specific features such as a shared virtual IP, Keepalived, DNS configuration synchronisation, and optional DHCP continuity. These are capabilities of the Pi-hole integration, not permanent limits or assumptions of the High Availability module.

Future providers and applications can use the same High Availability framework while supplying their own:

node topology and connection requirements;
validation and health checks;
agent actions;
deployment method;
configuration synchronisation rules;
failover and recovery controls;
integration-specific safety boundaries.

The pages and actions shown for a cluster are capability-driven. A future integration does not need to behave like Pi-hole or use Keepalived, DNS, DHCP, or a two-node topology.

Beta notice: High Availability is intended for controlled testing on a trusted private network or VPN. Validate backups and recovery procedures before relying on it for an important service.

How Kaya fits into your service

Kaya is the management and coordination plane. It is not placed in the network traffic path and should not become a dependency for the protected service to keep running.

Users and devices
       |
       v
Protected provider or application service
       |
       +---- Service nodes and local failover continue operating
       |
       +---- Kaya observes, coordinates, records, and applies approved changes

For the current Pi-hole integration, DNS, DHCP, Keepalived, and the node agents run on the Pi-hole hosts. If Kaya is unavailable, the last deployed local configuration continues to operate and automatic failover can still occur when it has been enabled and its local safety checks pass.

The High Availability module has three top-level areas:

Overview summarises protected services, current health, and recent clusters.
Clusters lists configured service clusters and opens their operational views.
Providers/Apps shows the integrations Kaya currently supports and the capabilities available for each one.

Select Create Cluster to choose a provider or application before entering any node details. Connection settings created during this workflow belong to High Availability. They are not created inside another Kaya module merely because an integration also appears there.

Before you begin

For any integration:

Open Providers/Apps and confirm that the required provider or application is supported.
Read its capability and platform requirements.
Prepare the required nodes and a tested service-level backup.
Confirm that Kaya can reach each node using the integration's required connection method.
Decide which node or service instance is the initial configuration authority.
Plan a maintenance window for deployment and the first controlled failover test.

For the current Pi-hole Beta, also confirm:

two Pi-hole v6 nodes are available;
both nodes and the proposed virtual IP are on the same Layer 2 IPv4 network;
the virtual IP is unused;
each Pi-hole works independently before it is added to the cluster;
both nodes use compatible Pi-hole versions and configuration;
you know whether Pi-hole or another service provides DHCP;
local firewalls allow the required Pi-hole, agent, VRRP, and virtual-IP traffic.

Enable the module

An administrator can enable High Availability from:

Site Administration → Experimental Features → High Availability

Disabling the module hides High Availability and stops Kaya's HA management jobs. It does not remove the local provider/application software, contact the protected nodes to uninstall anything, or delete stored cluster history.

Create a cluster

Open High Availability → Clusters.
Select Create Cluster.
Choose the provider or application.
Enter a clear cluster name.
Complete the integration-specific cluster and node fields.
Test each connection.
Save the cluster.

The provider/app selection is important: it determines the validation checks, supported node roles, agent capabilities, deployment workflow, synchronisation categories, and failover controls Kaya can safely offer.

Current Pi-hole fields

The Pi-hole integration asks for:

an active and standby Pi-hole node;
the address and application credential for each node;
a shared virtual IPv4 address and prefix;
the local network interface used by each node;
a unique VRRP router ID;
node priorities;
whether DHCP is external or Pi-hole-managed.

Use Test connection while entering the node details. A successful connection test proves that Kaya can reach and authenticate to the supplied Pi-hole endpoint; it does not replace the complete cluster validation.

To identify the interface that reaches the virtual IP from a Pi-hole host, run:

ip route get <virtual-ip>

Use the interface shown after dev, such as eth0 or ens18. Do not copy an interface name from a different host without checking it locally.

Validate the cluster

Open Setup & maintenance → Validation after saving the cluster.

Validation is read-only. It checks the provider/application version, authentication, required API capabilities, service health, configuration access, and integration-specific prerequisites. Unknown high-risk results fail closed and block deployment.

For Pi-hole, resolve every blocking result before continuing. A healthy DNS response alone is not enough; Kaya must also be able to authenticate and read the supported configuration required for synchronisation and recovery.

Re-run validation whenever you change:

a node address, port, credential, or interface;
the virtual IP or network prefix;
the provider/application version;
DHCP ownership;
an integration setting that affects deployment or failover.

Install and maintain node agents

Some integrations use a small Kaya agent on each protected node. The agent reports health and carries out a fixed, integration-specific set of actions. It cannot accept arbitrary shell commands from Kaya.

For Pi-hole:

Open Setup & maintenance → Agents.
Generate the install command for the first node.
Run the displayed command on that Pi-hole.
Wait for the node to show Live and Registered.
Repeat for the second node.

Registration tokens are short-lived, single-use, and bound to one cluster and node. After registration, the agent uses its own cryptographic identity.

The Agents page shows:

installed agent version;
version available from Kaya;
update status;
last heartbeat;
observed role;
DNS, DHCP, and service ownership state;
update/reinstall, revoke, and uninstall guidance.

A normal agent update keeps the registered identity and cluster link. Re-registration is only required when the identity has been revoked, removed, or deliberately rotated. Use the uninstall instructions shown by Kaya when permanently removing a node agent; revoking an agent in Kaya does not itself uninstall files from the node.

Deploy protection

Deployment is integration-specific. Kaya only shows deployment controls supplied by the selected provider/app integration.

Current Pi-hole deployment

Open Setup & maintenance → Keepalived.

Before deployment, Kaya requires:

current, registered agents on both nodes;
successful read-only validation;
valid network interfaces;
a virtual IP on the nodes' shared IPv4 subnet;
a unique VRRP router ID;
acknowledgement that this deployment configures Keepalived and does not independently hand control of the network to Kaya.

Kaya generates a restricted Keepalived configuration and fixed transition hooks. The agent:

backs up the existing managed state;
validates the generated configuration;
installs only the managed Kaya include and hooks;
reloads Keepalived;
reports the resulting checksum, runtime state, and virtual-IP ownership;
rolls back if validation or reload fails.

The expected steady state is:

Keepalived is running on both nodes;
exactly one node owns the virtual IP;
the higher-priority healthy node is active;
the other node is standby;
both nodes report the deployed configuration generation.

If deployment fails, Kaya displays the bounded diagnostic returned by the node. Resolve that exact error before deploying again.

Keep configuration aligned

Open Sync to review configuration monitoring and synchronisation.

Kaya uses an explicit copy direction. It does not merge competing edits or use last-write-wins. The displayed source is authoritative for that plan, and the destination is backed up before any write.

Manual synchronisation

Select Check for differences.
Review every supported configuration category.
Confirm the copy direction.
Approve destructive differences separately.
Select the backup-and-synchronise action.

Kaya reads the destination back after the write. If verification fails, it restores the backup.

Automatic synchronisation

After the cluster is healthy and a manual synchronisation has been tested, an administrator can enable automatic configuration sync.

For the Pi-hole integration:

Kaya regularly checks the current active and standby nodes;
the current service authority is copied to its peer;
a recovered node returns as standby and is brought back into alignment;
deletions remain separately controlled unless automatic deletion approval was explicitly enabled;
dynamic DHCP leases are not treated as ordinary configuration records.

The Sync page shows whether monitoring and automatic sync are active, the copy direction, last check, last successful application, next check, and any drift or blocker. The cluster Overview carries the same headline state for day-to-day use.

DHCP continuity

DHCP is a capability of the current Pi-hole integration, not a requirement of the general High Availability framework.

External DHCP

Choose external DHCP when a router, firewall, Windows server, or another service provides DHCP. Kaya does not enable, disable, synchronise, or fail over that external DHCP service.

Pi-hole-managed DHCP

When Pi-hole provides DHCP:

only the node owning the virtual IP may run DHCP;
reservations and supported DHCP configuration follow the controlled configuration-sync process;
active leases are validated and staged securely on the standby;
the standby does not import staged leases into a live DHCP service while it remains standby;
conflicting, invalid, stale, or ambiguous lease state blocks DHCP promotion;
Kaya never becomes the DHCP server.

Open DHCP to see the latest validation, lease count, snapshot generation, conflicts, last check, and last safely staged time.

Test failover

Complete a controlled failover before enabling automatic failover.

Confirm both agents are live.
Confirm exactly one node owns the service address.
Confirm synchronisation and, when applicable, DHCP continuity are current.
Open Failover.
Review the source, destination, and readiness checks.
Start the controlled failover.
Verify the protected service through its shared endpoint.
Review the Activity timeline and node roles.

For Pi-hole, test DNS against the virtual IP. If Pi-hole provides DHCP, also confirm that the promoted node is the only node running DHCP.

Automatic failover is opt-in. Automatic failback is disabled: a recovered former active node returns as standby so that recovery does not trigger an unexpected second interruption.

Day-to-day operation

Use the cluster Overview after onboarding is complete. It updates live and is intended to answer:

Is the protected service healthy?
Which node currently owns or serves it?
Are all agents current and reporting?
Is configuration in sync?
Is continuity data current where the integration requires it?
Are there active alerts?
Is automatic failover enabled?
When did Kaya last receive current state?

Use the remaining pages when more detail is required:

Nodes manages connection and node settings.
Sync explains configuration alignment.
DHCP appears when the integration supports DHCP continuity.
Activity retains operational events and alerts.
Failover provides controlled handover, automatic-failover controls, testing, and recovery history.
Setup & maintenance contains validation, agent, and deployment tasks.

Live screens update automatically. A Delayed, Stale, Offline, or Connection lost state means Kaya has not received sufficiently current evidence; it does not necessarily mean the protected service itself has stopped.

Connect another Kaya module

High Availability owns cluster setup and failover. Other modules can consume the stable logical service exposed by a healthy cluster without taking ownership of HA.

Current DNS Manager integration

A deployed, healthy Pi-hole cluster with one current virtual-IP owner can be selected in:

Site Administration → DNS Manager settings → Pi-hole connection → Connection source

Choose Kaya HA Pi-hole Cluster, then select the cluster and save the provider.

DNS Manager continues to treat it as one logical provider through the virtual IP. High Availability manages the nodes and active ownership behind that endpoint. Existing DNS Manager provider identity, linked IP details, observations, investigations, client data, and history remain preserved when an existing standalone provider is moved to the cluster connection source.

Users who only have one Pi-hole can continue using the standalone DNS Manager connection. High Availability is optional.

Future integrations may connect to different Kaya modules or remain entirely self-contained. Their guide sections will describe those boundaries without changing the ownership model: cluster setup stays in High Availability.

Alerts and reports

Open Activity for node, deployment, synchronisation, failover, split-brain, and recovery events. Events created locally while Kaya is unavailable are replayed when connectivity returns using stable event identities.

Use Download report to obtain a redacted operational report for troubleshooting. Secrets, registration tokens, and raw credentials are not included.

Review critical and warning alerts before acknowledging them. Acknowledgement records that an operator has seen the alert; it does not repair the underlying condition.

Remove a cluster safely

Removing a cluster from active HA views is deliberately separate from uninstalling node software or deleting data in another module.

Disable automatic synchronisation and automatic failover.
Confirm which node should continue serving the application.
Follow the integration's removal or rollback procedure.
Use the agent uninstall instructions if the agents are no longer required.
Repoint consuming modules or clients away from the HA service endpoint where necessary.
Use the cluster's Danger zone and complete the typed confirmation.

Cluster removal is a soft deletion. Kaya preserves nodes, connection references, validation records, DNS links, linked IP details, and operational history. Data remains until the user explicitly deletes it through the module that owns that data.

For Pi-hole, removing the Kaya cluster does not automatically remove Keepalived or reconfigure DNS/DHCP on either host. Complete the displayed rollback and uninstall steps first.

Troubleshooting

The page shows an old role after a failover

Check the heartbeat age and Live indicator. The Pi-hole agents make the local decision and then report it to Kaya. If an agent is offline, Kaya cannot safely infer current ownership from an old heartbeat.

Do not manually force both nodes active. Restore agent connectivity and use the reported VIP ownership and failover diagnostics.

Both nodes appear to own the virtual IP

Treat this as a split-brain condition:

Do not enable DHCP manually on either node.
Restore communication between the nodes.
Check VRRP traffic, firewall rules, interface selection, router ID, subnet, and duplicate addresses.
Confirm only one node owns the virtual IP.
Re-run validation before restoring automatic failover.

A Pi-hole reports DNS failure after promotion

Confirm that Pi-hole FTL is running, the promoted node owns the virtual IP, and the generated transition diagnostic is clear. Review the Activity and Failover pages before attempting another transition.

Synchronisation reports that the plan changed

The source or destination configuration changed after the plan was created. Generate a new comparison and review it. Kaya intentionally refuses to apply a stale plan.

Deployment reports a Keepalived configuration error

Use the diagnostic shown for the affected node. Correct the interface or conflicting local configuration, then deploy a new generation. Do not bypass the validation or edit the generated Kaya block while it is managed.

Security and operational guidance

Keep the main Kaya interface on a trusted private LAN or VPN.
Use HTTPS and explicit trusted-proxy IPs or CIDRs.
Protect provider/application credentials and node administrator access.
Verify node identity and connection details before enrolment.
Keep Kaya and node agents updated.
Retain service-native backups outside the cluster.
Test controlled failover and recovery after meaningful platform changes.
Never treat a green dashboard as a substitute for an independent service test.
Do not expose agent bootstrap tokens, runtime secrets, or unredacted diagnostics.

Current Beta limitations

The High Availability framework is provider/app-neutral, but the first shipped integration currently supports:

Pi-hole v6;
two nodes;
Debian, Ubuntu, or Raspberry Pi OS hosts;
a Layer 2 IPv4 virtual IP using Keepalived/VRRP;
guarded Pi-hole configuration synchronisation;
optional Pi-hole DHCP continuity;
controlled and opt-in local automatic failover;
no automatic failback.

These describe the Pi-hole Beta integration. They do not define the topology or capabilities that future High Availability providers and applications must use.