Upgrade between v5 releases

This page takes a running Flow v5 install to a later v5 release. It's for operators. To move a v3 install to v5, see Upgrade from v3 instead: v3 stops first, and the upgrade doesn't roll.

Roll out a later release

Later v5 releases upgrade with a rolling update. The new release migrates in its first pod while the previous release keeps serving.

1. Read the release's Upgrading notes.

2. Back up the database.

3. Deploy all three images at the new tag, with core rolling one pod at a time:

   strategy:
     type: RollingUpdate
     rollingUpdate:
       maxSurge: 1
       maxUnavailable: 0

   One new pod runs the migrations while the old pods serve. Once it's ready, the rest replace the old pods one at a time and start against the migrated database without waiting.

What to watch during the rollout

• Mixed versions. During the rollout, the previous release keeps serving against the migrated database: every migration stays compatible with the previous release. That holds between v5 releases only. A v3 upgrade stops v3 first.
• Startup probe. The new pod is starting for the whole of its migration. Keep the probe sized for the largest migration the release notes describe.
• When a migration fails, the new pod doesn't start, and the rollout stalls with the old pods serving. Read its log with kubectl logs <new-pod> -n <namespace>, fix the cause, and delete the pod. The interrupted step runs again on the next start. Never edit flow_sys_migration_changelog.
• Turning migrations off. flamingock.enabled=false (FLAMINGOCK_ENABLED=false) starts core without running migrations. Core then runs against whatever shape the database has. Migrations are the only thing that builds indexes and seeds settings, roles and catalogue changes, so a release started this way against a database its migrations haven't reached can fail requests, or run without its indexes. Use it only for a replica of a release whose migrations have already run against this database.

Next steps

• What's new: the release notes, with each release's Upgrading items.
• Configure health probes: core's startup probe and the other probes.
• Replicas and the migration lock: how replicas that start together share the migrations.
• Configuration reference: core, webapp and dispatcher link properties, with their defaults.
• Upgrade from v3: moving a v3 install to v5.