Uninstall the control plane

Uninstalling removes the control plane from its host. It does not touch your clusters: their workloads keep running, with nothing managing them. Decide first what you want for each cluster.

Before you startCopy Anchor Link

• Decide what happens to the clusters. Remove each cluster in the console first if you want NebulaCtrl to forget it cleanly. Without a control plane, the agents have nothing to talk to.
• Back up if you might come back. Take a dump and keep .env. See Back up and restore the control plane. Without the master key, a restored database cannot open its secrets.
• Export audit events you need to keep: select Export CSV on the Activity page.
• Know the rollback. Until step 5, nothing is deleted: the database volume and /opt/nebula stay on disk, and running the installer again brings the installation back. Step 5 is the point of no return.

The commands assume the install directory /opt/nebula. Replace it if you installed elsewhere, and prefix docker with sudo if your user cannot reach the Docker socket.

1. Decide about the clustersCopy Anchor Link

For each cluster you want removed from NebulaCtrl:

1. Unbind its environments or move them to another cluster. Removal is refused while an environment is bound.
2. Open the cluster's Settings tab. In the Remove CLUSTER_SLUG row, select Remove, type the cluster slug and select Remove cluster.

NebulaCtrl forgets the cluster and its nodes. The message in the console is explicit: workloads keep running and K3s stays installed. To remove K3s, run /usr/local/bin/k3s-uninstall.sh on each server node of the cluster.

The cluster install also leaves other changes on each node: the WireGuard mesh (nebula0, /etc/nebula/mesh and the nebula-mesh-sync timer), ufw rules, a fail2ban jail, and a drop-in that turns off SSH password login. Review and remove them yourself if you reuse the node.

A cluster you leave in place keeps running its agent, which no longer has a control plane to talk to.

2. Stop the updaterCopy Anchor Link

Skip this if the updater service is not installed, which is the case when you installed with --no-updater or on a host without systemd.

sudo systemctl disable --now nebula-updater

sudo rm /etc/systemd/system/nebula-updater.service

sudo systemctl daemon-reload

3. Stop the control planeCopy Anchor Link

docker compose -p nebula -f /opt/nebula/deploy/compose.prod.yaml --env-file /opt/nebula/.env --profile local-db down

Omit --profile local-db when you use an external database. This removes the containers and the Compose network. It keeps the nebula_postgres-data volume that holds the bundled database.

4. Remove what is around itCopy Anchor Link

• Remove the reverse proxy site and its certificate.
• Delete the OIDC client at your identity provider.
• Remove the DNS record for the public URL.
• For an external database, drop the database yourself. NebulaCtrl never removes it.
• Object stores you connected keep their data. Delete the buckets with your storage provider if you no longer need the backups in them.

5. Delete the dataCopy Anchor Link

Remove the bundled database volume, the image and the install directory.

docker volume rm nebula_postgres-data

docker image rm ghcr.io/nebulactrl/nebula:VERSION

VERSION is the release you ran. docker image ls ghcr.io/nebulactrl/nebula lists it.

sudo rm -rf /opt/nebula

The directory holds .env and its .bak copies, the Compose file, the updater binary and the updater's logs.

VerifyCopy Anchor Link

docker ps --filter name=nebula

The list is empty.

systemctl status nebula-updater

The service is reported as not found.

If it goes wrongCopy Anchor Link

You removed the containers but want the installation back. Run the installer again with the same directory. It finds .env and the volume, keeps the master key and starts the control plane on the existing data:

curl -fsSL https://get.nebulactrl.dev | sh -s -- --dir /opt/nebula

You already ran step 5. Install again, then restore the dump and .env you saved. See Back up and restore the control plane. If you saved nothing, the installation cannot be recovered.

docker volume rm says the volume is in use. A container still uses it. Run the step 3 command again and check docker ps -a --filter name=nebula.