Remove an HA controller

Overview

A healthy OpenZiti controller sometimes needs to leave its high-availability cluster for planned reasons, such as host decommissioning, scaling down, or moving the cluster to different infrastructure. This guide removes the controller cleanly with kziti. You first remove the controller from Raft membership without losing quorum, then tear down the docker compose stack on the removed host. As a result, the remaining controllers stay authoritative and the cluster continues to operate without interruption.

If the controller is already dead and quorum is lost, use Recover from quorum loss instead.

Prerequisites

Before you begin, confirm the following:

• The controller you are removing is healthy and reachable.
• The remaining controllers can maintain quorum without it. More than half of the surviving members must be voters.
• Shell access on a remaining controller host and on the host being removed.

Solution approach

This guide progresses through the following phases:

1. Remove the member from Raft.
2. Tear down the removed host.

Detailed steps

Remove the member from Raft

1. On a remaining controller host, remove the target member from Raft membership:

   kziti deploy ha remove-member --node ziti-c-2

   --node is the node name of the controller being removed. The command tells the cluster leader to remove the target from membership. The target controller is no longer authoritative for any cluster state once this returns.

2. Verify that the member has been removed:

   docker compose -f /opt/kziti/docker-compose.yml exec ziti-controller \
     ziti agent cluster list

   The removed node should no longer appear in the list. Remaining controllers should still report a healthy leader.

Tear down the removed host

1. On the host that was removed, stop and uninstall the kziti stack:

   kziti deploy uninstall --remove-data --yes

   This stops all containers, removes the docker compose project, and deletes the /opt/kziti data directory. The host no longer participates in the cluster in any way.

   If you intend to redeploy the same host as a fresh HA controller, you can omit --remove-data to retain the old data directory for inspection. For a planned removal followed by a fresh install, removing data is the safer default.

Common troubleshooting steps

• The removed node still appears in the cluster list. Confirm that kziti deploy ha remove-member returned successfully on a remaining controller host. Run ziti agent cluster list again, because membership changes propagate through the cluster leader.
• The remaining controllers lose quorum after removal. More than half of the surviving members must be voters. Restore quorum with Recover from quorum loss, then remove the controller only when the cluster can maintain quorum without it.
• The removed host still holds OpenZiti data. Run kziti deploy uninstall --remove-data --yes on that host to delete the /opt/kziti data directory. Omit --remove-data only when you want to retain the directory for inspection.