feat: allow configuring the Deployment update strategy#328
Merged
ChrisJBurns merged 1 commit intobackstage:mainfrom May 4, 2026
Merged
feat: allow configuring the Deployment update strategy#328ChrisJBurns merged 1 commit intobackstage:mainfrom
ChrisJBurns merged 1 commit intobackstage:mainfrom
Conversation
Adds a new `backstage.strategy` value that maps to the Deployment
`spec.strategy` field, so operators can opt into `Recreate` (or
`RollingUpdate` with `maxSurge: 0`) to guarantee a single Backstage
pod runs at a time.
Motivation: Backstage plugins (catalog, auth, etc.) run knex database
migrations during plugin initialization. Under the default
RollingUpdate strategy (maxSurge 25%) a new pod starts while the old
one is still running, and both race the `knex_migrations_lock` row.
If a pod is killed mid-migration, the lock stays set (`is_locked=1`)
and every subsequent pod fails catalog startup with
`MigrationLocked: Migration table is already locked`, requiring manual
DB intervention. Letting operators pin the strategy to Recreate (or
maxSurge 0) prevents concurrent migration attempts entirely.
The field defaults to `{}` and is only rendered into the manifest when
set, preserving the current behavior (Kubernetes default RollingUpdate
25%/25%) for existing installs.
Signed-off-by: Luis Brito <luis.brito@digitalfemsa.com>
rm3l
approved these changes
Apr 27, 2026
ChrisJBurns
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
backstage.strategyvalue that maps to the Deploymentspec.strategyfield so operators can opt intoRecreate(orRollingUpdatewithmaxSurge: 0) and guarantee that only one Backstage pod runs at a time.Default behavior is unchanged: when
backstage.strategyis unset (the default{}), no strategy block is rendered and Kubernetes keeps applying its own default (RollingUpdatewithmaxSurge: 25%/maxUnavailable: 25%).Motivation
Backstage plugins (e.g.
catalog,auth) run knex database migrations during plugin initialization on every pod startup. Under the current defaultRollingUpdatestrategy, a new pod starts while the old pod is still running, and both race theknex_migrations_lockrow. If either pod is killed mid-migration (OOM, node drain, probe failure during the rollout), the lock stays set (is_locked = 1) and every subsequent pod fails catalog startup with:Recovery requires manual DB intervention — not great on production.
Allowing operators to pin the strategy to
Recreate(orRollingUpdatewithmaxSurge: 0) removes the concurrent-migration race entirely for single-replica deployments (which is the common case for Backstage).Usage
or
Changes
values.yaml: addbackstage.strategy(default{}) with helm-docs comment.values.schema.tmpl.json: add JSON schema entry with examples;values.schema.jsonregenerated by thejsonschema-dereferencepre-commit hook.templates/backstage-deployment.yaml: conditionally renderspec.strategyfrom.Values.backstage.strategyusingcommon.tplvalues.renderso templated values (e.g. global settings) are supported.ci/strategy-values.yaml: new CI test case (RollingUpdatewithmaxSurge: 0).Chart.yaml: bump chart version2.6.3→2.7.0(minor — new additive feature, backward-compatible).README.md: regenerated byhelm-docs.Test plan
pre-commit run --all-filespasses (helm-docs, jsonschema-dereference, codespell).ct lint --charts charts/backstagepasses against allci/*-values.yamlfiles including the newstrategy-values.yaml.helm templatewith default values produces nostrategyblock in the rendered Deployment (preserves existing behavior).helm templatewithci/strategy-values.yamlcorrectly renders thestrategyblock withmaxSurge: 0,maxUnavailable: 1.CONTRIBUTING.md.