Upgrade the control plane

An upgrade replaces the control plane container with the new release's image. Pending database migrations run when the new container starts. Clusters and their workloads are not touched.

Before you startCopy Anchor Link

• Take a backup. Neither the console update nor the installer backs up the database. Follow Back up and restore the control plane, and keep the dump with its matching .env.
• Read the changelog for every release between the running version and the target. The changelog announces breaking changes to the HTTP API and to nebula.toml.
• Write down the running version. You need it to go back. It is on Settings > Updates and in the version pill in the header.
• Choose a path. The console path needs the nebula-updater service on the host, and an owner of the Default organization. The installer path needs a shell on the host. The installer path is the only way to choose a version other than the newest.
• Know the rollback. If the new release does not come up, the updater puts the previous one back by itself. By hand, you re-run the installer with the previous version and --allow-downgrade. Migrations are never reversed, so a release that cannot run on the migrated schema needs the backup restored. See If it goes wrong.

The control plane is unreachable for the few seconds it takes to replace its container. The console reconnects by itself.

1. Update the control planeCopy Anchor Link

2. Update the cluster agentsCopy Anchor Link

A control plane update does not update any agent. Follow Update a cluster agent for each cluster. Settings > Updates lists the clusters whose agents trail the control plane.

VerifyCopy Anchor Link

curl -s http://127.0.0.1:8080/api/v1/version | grep -o '"version":"[^"]*"'

Use your listen address if it is not the default.

"version":"0.39.0"

• The value is the release you installed.
• Settings > Updates shows the result as Updated to vX.Y.Z.
• Open the console and a project. Clusters show connected after their agents reconnect.

If it goes wrongCopy Anchor Link

The console shows "Update to vX.Y.Z failed and was rolled back". The installer failed, or the new release did not answer with its version, so the updater ran the previous release's installer with --allow-downgrade, and the control plane runs the previous version again. The update history lists it as Rolled back. Read the installer output with Show installer log, fix the cause, then request the update again. On the host the log is /opt/nebula/updater/install-VERSION.log, and the service log is journalctl -u nebula-updater.

The console shows "Update to vX.Y.Z failed". The installer failed and so did the reinstall of the previous release. The message states what the control plane answers now and the command that puts the previous release back:

curl -fsSL https://get.nebulactrl.dev/vPREVIOUS/install.sh | sh -s -- --dir /opt/nebula --version PREVIOUS --allow-downgrade

Replace PREVIOUS with the version you wrote down. Run it on the host.

The console shows "Update to vX.Y.Z failed" with "The updater stopped reporting during the update". The updater service went away mid-update, and the control plane wrote the update off after 15 minutes without contact. The control plane runs the version named in the message. Check journalctl -u nebula-updater, then restart the service with sudo systemctl restart nebula-updater.

The updater refuses the update. The message begins The updater refused to install vX.Y.Z and names the reason, such as a version that is not newer than the installed one or one missing from the release index. Nothing was run.

The previous release does not start on the migrated schema. Go back with the command above, then restore the dump you took before the upgrade. Anything written after the dump is lost, and clusters enrolled after it are unknown to the restored database. See Back up and restore the control plane.

The container never becomes healthy. The installer prints the last 40 log lines and stops. .env and the Compose file are already in place, so fix the cause and run the installer again. For the cause, see Control plane troubleshooting.