Remove an HA controller
Use this procedure when a controller is healthy and you want to remove it cleanly — host decommissioning, scaling down, or moving the cluster to different infrastructure. The controller is removed from Raft membership without losing quorum, and the docker compose stack on the host is then torn down.
If the controller is already dead and quorum is lost, use Recover from quorum loss instead.
- 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).
- You will need shell access on a remaining controller host and on the host being removed.
Step 1. Remove the member from Raft
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.
Verify it 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.
Step 2. Tear down the removed host
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 — but for a planned removal followed by a fresh install, removing data is the safer default.