Skip to main content
Version: Developer

Tear down a kziti deployment

Overview​

A kziti-managed OpenZiti host eventually reaches end of life, whether you are decommissioning a controller, retiring a private router, or rebuilding from scratch. This guide stops and removes a kziti-managed OpenZiti deployment from a host. You decide whether to keep the persistent OpenZiti state for a later reinstall or wipe the host clean. The procedure applies to single-controller setups, individual high availability (HA) members, and standalone private router hosts.

Prerequisites​

Before you begin, confirm the following:

  • Shell access to the host that runs the kziti-managed OpenZiti deployment, with permission to run kziti and sudo.
  • Any backups or exports of OpenZiti state that you need to keep, if you intend to delete the data directory. The warning below details the data this procedure can remove.
  • Confirmation that the host is not a single HA member you intend to remove while the cluster keeps running. To remove one HA controller and keep the cluster online, follow Remove an HA controller instead. That procedure runs remove-member first, then teardown.

Solution approach​

This guide progresses through the following phases:

  1. Choose a teardown scope.
  2. Stop the stack and optionally wipe persistent data.
  3. Remove the kziti binary.

Detailed steps​

Choose a teardown scope​

Decide how much state to remove before you run any command:

  • Stop the stack only. Stops the containers and removes the Docker Compose project, but keeps the data directory. Choose this scope to reinstall on the same host or to inspect state offline.
  • Stop and wipe. Stops the stack and deletes the persistent data directory, leaving the host clean apart from the kziti binary.
Destructive data removal

The --remove-data flag is destructive. It deletes the persistent OpenZiti state on the host, including the controller database, router certificates, and identity material. Confirm that you have any backups or exports you need before you run with this flag.

Stop the stack and optionally wipe persistent data​

  1. To stop the containers and remove the Docker Compose project while keeping the data directory in place, run the following command:

    kziti deploy uninstall --yes

    The data directory at /opt/kziti/data is left intact. If you used a non-default --install-dir, the data directory is <install-dir>/data.

  2. To stop the stack and also delete the persistent data, run the following command instead:

    kziti deploy uninstall --remove-data --yes

    This command stops all containers, removes the Docker Compose project, and deletes the data directory. The host is left clean, and only the kziti binary remains on PATH.

Remove the kziti binary​

To remove the kziti binary from the host as well, run the following command:

sudo rm /usr/local/bin/kziti

Common troubleshooting steps​

  • The data directory still exists after uninstall. The kziti deploy uninstall --yes command keeps the data directory by design. To delete it, rerun the uninstall with the --remove-data flag.
  • The uninstall removed data you needed. The --remove-data flag permanently deletes the controller database, router certificates, and identity material. Restore from a backup or export taken before the teardown, as kziti cannot recover this state.
  • A single HA member was removed but the cluster is now unhealthy. Teardown alone does not remove a member from the cluster quorum. To remove one HA controller cleanly, follow Remove an HA controller, which runs remove-member before teardown.
  • The kziti command is still available after teardown. The uninstall commands do not remove the kziti binary. Run sudo rm /usr/local/bin/kziti to remove it from PATH.