Updates & Maintenance
Update QuickStack, manage disk space, and perform k3s cluster upgrades.
Updating QuickStack
QuickStack checks for new versions automatically and allows in-UI updates without SSH access.
Check and install an update
- Go to QuickStack Settings → Updates & Add-Ons.
- View your installed version and the latest available version.
- When an update is available, click Update QuickStack.
- QuickStack installs the new version and restarts. The dashboard is temporarily unavailable during restart.
Canary channel
To test the latest features before they reach the stable channel, enable Use Canary Channel for Updates.
Canary builds may be unstable. Not recommended for production.
Disk space & cleanup
Docker images, build logs, and temp files accumulate over time. QuickStack provides cleanup tools:
- Go to QuickStack Settings → Maintenance.
- Available actions:
| Action | What it does |
|---|---|
| Purge Images | Deletes unused build images from the internal registry |
| Cleanup Old Build Jobs | Removes containers from completed build jobs |
| Cleanup Temp Files | Deletes temporary files from operations |
| Delete Old App Logs | Clears historical application logs |
| Delete Orphaned Containers | Removes pods no longer associated with active apps |
k3s and QuickStack manage old data/images automatically. Use these cleanup options only when experiencing disk space issues. Copies of pulled external images (e.g. MariaDB) are managed by k3s and cannot be removed through this interface.
K3s cluster upgrades
Upgrade the underlying k3s Kubernetes distribution from the UI.
Install the System Upgrade Controller (first time)
- Go to QuickStack Settings → Updates & Add-Ons.
- In K3s Cluster Upgrades, click Install Controller if not already installed.
Perform the upgrade
- View current and available k3s versions.
- Click Start Upgrade and confirm after reviewing warnings.
The upgrade process:
- Upgrades master/control-plane nodes first
- Upgrades worker nodes one at a time (cordons + drains each node)
- Apps on a draining node are rescheduled to other nodes and may experience brief downtime
Before upgrading k3s
- Ensure system backups are enabled and recent
- Verify volume backups are configured
- Expect brief downtime during node restarts
k3s version channels
QuickStack keeps you on a chosen minor-version channel (e.g. v1.32). Moving between minor versions requires manual action here.
Cluster Add-ons
Optional cluster components — such as Longhorn (distributed storage) and CertManager (TLS certificates) — are installed and updated from QuickStack Settings → Updates & Add-Ons → Cluster Add-ons.
Each add-on card shows its status, installed version, and the next available version. Depending on the add-on you can Install, Update, or Remove it. Updates show a warning with the items to check first (for example, recent backups before a Longhorn update).
See Cluster Add-ons for the full workflow.
Troubleshooting QuickStack itself
From QuickStack Settings → Maintenance (or Updates & Add-Ons):
- Open QuickStack Logs — view live logs of the QuickStack system container. This is admin-only; QuickStack system logs are not available to non-admin users.
- Force Update Registry — restarts the internal container registry if image builds are failing.
- Delete All Network Policies — emergency action to remove all network policies if they cause connectivity issues. Use with caution.