Skip to main content
Migration Notice
We're migrating documentation from the old portal into this one. Some things may look a little different or out of place in the meantime — we know, and we're working to get it right. If something's unclear or doesn't look right, let us know.

Software Update

The Software Update tab lets an administrator replace the running console container without accessing the host directly. Upgrades are Docker image tar files, which you upload here in the browser or stage from the appliance shell with aisec-upgrade. Download the console upgrade tar for a release from the Superna support site.

Kubernetes and Helm Deployments​

This tab does not apply when the console runs from the Helm chart, and it appears greyed out on that type of deployment. Upgrade a Helm-deployed console by updating the console image tag in your Helm values and running helm upgrade. See Install on Kubernetes. Uploading a tar to the console has no effect and only uses disk space.

How Upgrades Work​

On the OVA appliance, the console runs as a Docker container owned by a systemd service, aisec-console-app.service. A running application cannot replace its own container, so the swap is split between three parts on the host.

  1. The console stores the uploaded image tar in /opt/superna/upgradeimages/ and writes bundle-meta.json (image tag, size, and SHA-256). When you click Apply Upgrade, it also writes a .trigger file, and then exits.
  2. The upgrade watcher (aisec-console-upgrade-watcher.service) sees the trigger. It runs as an unprivileged account with no Docker access. It records the current image as the rollback target, writes the new image tag, and asks systemd to restart aisec-console-app.service. Restarting the console and its database services is the only privilege it has.
  3. systemd restarts the console. Before the container starts, a root-owned loader verifies the SHA-256 of the staged tar and loads it into Docker. The container then starts on the new image. Older console images are pruned. The newest three, the running image, and the rollback target are kept.

The watcher then checks the console's health endpoint and rolls back if the console does not become healthy. See Automatic Rollback.

Before You Begin​

  • Create a backup. See Backup.
  • Plan a maintenance window. The console is unavailable for about 1 to 2 minutes during the swap.

Upload the console upgrade tar file in the browser (Manual upload) or stage it from the appliance shell. After the image reaches the Ready state, continue with Apply an Upgrade.

Manual Upload​

To upload the console upgrade tar (aisec-console-upgrade-<version>.tar) from your computer:

  1. Drag the .tar file onto the upload area, or click the area to browse for it.
  2. Click Upload. A progress bar shows the progress. Files are typically 1–2 GB, so the upload can take several minutes.
  3. After the upload, the console validates the file by checking the tar header and minimum size, and computes its checksums. The image then moves to the Ready state.

The Ready card shows the image tag, the MD5 checksum with a copy button, and the file size. If the staged build is the one already running, the card says so instead of offering an upgrade.

Upgrade from the Appliance Shell​

You can run the same upgrade on the appliance itself, without the browser.

sudo aisec-upgrade /path/to/aisec-console-upgrade-<version>.tar   # upgrade and wait for the result
sudo aisec-upgrade --dry-run /path/to/<tar> # validate only
sudo aisec-upgrade --status # running image, rollback target, watcher
sudo aisec-upgrade --rollback # return to the previous image

Both methods use the same staging directory and watcher, so an upload staged in the web interface and one staged from the shell replace each other.

Verify the checksum​

The Ready card shows an MD5 checksum. To confirm that the image was not corrupted in transit:

  1. On the machine that holds the original file, run md5sum /path/to/aisec-console-upgrade-<version>.tar on Linux or md5 /path/to/aisec-console-upgrade-<version>.tar on macOS.
  2. Compare the output with the MD5 value shown in the console.

If the values differ, dismiss the staged image and upload it again. Do not apply an image with a mismatched checksum.

Apply an Upgrade​

Use these steps after a manually uploaded image reaches the Ready state.

  1. In the Ready card, click Apply Upgrade.
  2. A confirmation dialog shows the build number and image tag. Review them, and click Apply Upgrade to proceed.
  3. An amber Replacing container banner appears while the container is replaced.
  4. After about 5–6 seconds the connection is lost. The page switches to Waiting for restart and checks the login endpoint every 3 seconds.
  5. When the new container responds, the page reloads automatically.

Total downtime is approximately 1 to 2 minutes, which covers the console restart and its startup.

On the OVA, uploading or applying fails with an error while an appliance maintenance operation is running, such as an installation update, a sizing change, a credential reset, or an OS-patch window. Nothing is changed. Apply the upgrade again when the operation has finished. The appliance's maintenance tools likewise refuse to start while an upgrade is in progress.

Automatic Rollback​

After the restart, the watcher checks the console's health endpoint (/api/health) every 10 seconds for up to 3 minutes. If the console does not become healthy:

  1. The watcher writes the previous image tag back and restarts aisec-console-app.service on it.
  2. The watcher writes an upgrade-failed.txt file with the reason for the failure, including a likely root cause read from the console log, for example out of memory, a database connection failure, or a port already in use.

The next time the console starts, a red Upgrade failed banner appears. Click Dismiss to clear the failure and return to the Idle state.

For details, check the watcher log on the appliance with sudo tail -50 /opt/superna/upgradeimages/upgrade-watcher.log (timestamps are UTC), or run sudo journalctl -u aisec-console-app.service.

If the previous version does not become healthy either, the console is usually unreachable. Connect to the appliance over SSH and check sudo aisec-upgrade --status, the watcher log, and the journal.

State Reference​

StateMeaning
IdleNo staged image. Only the upload section is shown.
UploadingThe image tar is being uploaded. A progress bar is visible.
ValidatingThe upload is complete. Tar header and minimum-size checks are running.
ReadyA validated image is staged. Apply Upgrade is available.
UpgradingThe container replacement is in progress.
FailedThe upgrade failed. Automatic rollback restored the previous container.
Upgrade and rollback both failedThe new container and the rollback attempt both failed. Manual intervention is required on the appliance. See Automatic Rollback.