Upgrade
Copy page
This guide shows you how to upgrade a Sluice deployment to a new version. The server applies the database migrations itself, so an upgrade is a backup and a rollout of the new image.
Versions and the changelog
Section titled “Versions and the changelog”Sluice uses Semantic Versioning. Before 1.0.0, a minor version can break compatibility. The CHANGELOG lists the changes of each version under Added, Changed and Fixed. Read the entries of every version between your version and the new one before you upgrade.
Each release pushes two images to the GitHub Container Registry, for linux/amd64 and linux/arm64:
| Image | Tags |
|---|---|
ghcr.io/alternayte/sluice |
<version>, <major>.<minor>, latest |
ghcr.io/alternayte/sluice-uv |
<version>, <major>.<minor>, latest |
Pin the full version tag, for example 0.4.0. The latest and <major>.<minor> tags move with each release. sluice version prints the version, the commit and the build date of a binary.
How migrations run
Section titled “How migrations run”The migrations are in the binary. sluice server applies every migration that the database does not have when it starts. sluice migrate applies them and exits.
| Property | Behaviour |
|---|---|
| Transaction | All new migrations run in one transaction, behind a transaction-scoped advisory lock. |
| Concurrent starts | When several instances start at the same time, each migration applies once. |
| Record | The table schema_migrations holds the applied versions. |
| Readiness | The migrations check of /readyz fails when the database and the binary have different migrations. |
| Pooler | Migrations run in the simple query protocol, so a transaction-mode pooler such as PgBouncer works. |
After a new version adds a migration, an instance of the old version fails its migrations check with migrations not current. A load balancer or a Kubernetes Service that reads /readyz then stops sending requests to the old instance.
Upgrade
Section titled “Upgrade”-
Back up the database and the object store. See Back up and restore.
-
Optional: apply the migrations with the new image before the rollout. The server also migrates at start, so this step only moves the migration time.
Terminal window docker run --rm -e SLUICE_DATABASE_URL="$SLUICE_DATABASE_URL" \ghcr.io/alternayte/sluice:0.4.0 migrateThe command prints
applied <n> migrations. -
Roll out the new version.
Terminal window helm upgrade sluice oci://ghcr.io/alternayte/charts/sluice --version 0.4.0 -n sluice --reuse-valueskubectl -n sluice rollout status deployment/sluiceThe chart version is the Sluice version. An empty
image.taguses the image of that version.Set
SLUICE_IMAGEin.envto the new release, for exampleghcr.io/alternayte/sluice-uv:0.4.0, or keeplatest. Then, in the directory of the compose file:Terminal window docker compose pulldocker compose up -dThe
postgres-datavolume keeps the database.Terminal window docker pull ghcr.io/alternayte/sluice-uv:0.4.0docker stop sluice && docker rm sluiceStart the new image with the same environment variables as before. Keep the same
SLUICE_MASTER_KEYS. -
Make sure that
/readyzreturns 200 on each instance. -
Run
sluice versionin the new image, or read the Version column on Settings → Instances.
What happens during a rolling upgrade
Section titled “What happens during a rolling upgrade”Old and new instances share one database while the rollout runs. An instance does this work when it gets SIGTERM:
| Work | What happens |
|---|---|
| New claims | The instance stops claiming task runs. The other instances claim them. |
| Process and inline task runs | The instance stops them. They end FAILED with the reason instance_shutdown, and the retry policy of the task applies. |
| Docker and kubernetes task runs | They continue without the instance. They become lost only when their runner sends no heartbeat for SLUICE_HEARTBEAT_TIMEOUT. |
| Leases | The instance releases its leases. Another instance takes each lease at its next attempt, within 5 seconds. |
| Exit | The process exits within SLUICE_SHUTDOWN_GRACE. |
The Helm chart sets terminationGracePeriodSeconds to shutdownGraceSeconds plus 10 seconds, so Kubernetes does not kill a pod before its shutdown ends.
Each release keeps the release before it working on the new database schema. A migration adds tables and columns, and a later release removes what the older one used. Thus upgrade one minor version at a time when you use a rolling rollout. To skip versions, stop all instances first.
From 0.4.0, an old instance stays ready while the database has a newer migration. An instance of 0.3.0 or earlier fails its migrations readiness check in that time. It still runs its tasks, but it gets no HTTP requests until the rollout replaces it.
Use a new flow feature, for example each or the wait task, only after every instance runs the new version. An old instance marks a flow with a field that it does not know as invalid.
A task image with inject_runner: false holds its own sluice binary. Update that image when a task uses a feature that is newer than the binary. Otherwise the task fails with reason runner_too_old.
To keep a long task safe across an upgrade, run it on the docker or kubernetes executor, or give it a retry policy. See Retry, time out and limit executions.
Roll back
Section titled “Roll back”Migrations go forward only. Each release keeps the release before it working on the new schema. Thus a rollback by one release works for the flows that use no new feature.
Restore the backup of step 1 and start the old version in these cases:
- An execution used a new feature.
- You go back more than one release.
Related pages
Section titled “Related pages”- Runbook: health checks and common errors.
- Deploy on Kubernetes with Helm: the chart values.
- Deploy with Docker Compose: the compose file.