Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(helm-charts): probe /healthz for readiness, not liveness [BYT-10353] (#21660)

h3n4l3e275494e0fe
diff --git a/docs/bytebase-1.1.7.tgz b/docs/bytebase-1.1.7.tgz
new file mode 100644
index 0000000000..cad7695207
Binary files /dev/null and b/docs/bytebase-1.1.7.tgz differ
diff --git a/docs/index.yaml b/docs/index.yaml
index 3cc3c4db29..7531f4b80d 100644
--- a/docs/index.yaml
+++ b/docs/index.yaml
@@ -1,6 +1,22 @@
apiVersion: v1
entries:
bytebase:
+ - apiVersion: v2
+ created: "2026-10-23T17:39:38.748262+08:00"
+ description: Safe database schema change and version control for DevOps teams.
+ digest: 026c44535993a8d1720e23caf7cd8cace6b470247ccc1be5107c0c25905d424a
+ home: https://www.bytebase.com/
+ icon: https://raw.githubusercontent.com/bytebase/bytebase.com/main/public/images/logo.svg
+ maintainers:
+ name: Bytebase
+ name: bytebase
+ sources:
+ - https://github.com/bytebase/bytebase
+ type: application
+ urls:
+ - bytebase-1.1.7.tgz
+ version: 1.1.7
- apiVersion: v2
created: "2026-07-28T10:44:46.236015+08:00"
description: Safe database schema change and version control for DevOps teams.
@@ -81,4 +97,4 @@ entries:
urls:
- bytebase-1.1.1.tgz
version: 1.1.1
-generated: "2026-07-28T10:44:46.23498+08:00"
+generated: "2026-10-23T17:39:38.747818+08:00"
diff --git a/docs/operations/upgrade.md b/docs/operations/upgrade.md
index e7749e1f2b..18d044c885 100644
--- a/docs/operations/upgrade.md
+++ b/docs/operations/upgrade.md
@@ -20,6 +20,10 @@ The bundled Helm chart still deploys a single replica by default, so HA rollouts
- Take the backup or snapshot your standard operating procedure requires before upgrading Bytebase.
4. **Confirm shared configuration is consistent.**
- Every HA replica should start with `--ha`, use the same `PG_URL`, and keep the same external URL during the upgrade.
+5. **Make sure nothing stops a migrating server.**
+ - Bytebase opens its HTTP port only after metadata migrations finish, so `/healthz` fails until then.
+ - A readiness probe or a load balancer health check that only removes the server from traffic is safe.
+ - A liveness probe, an orchestrator that replaces unhealthy tasks (such as an ECS service behind a load balancer), or a deploy that rolls back on timeout (such as `helm upgrade --atomic`) sends SIGTERM mid-upgrade. Give each a grace period or timeout above the expected migration time.
## Helm chart behavior during upgrades
@@ -48,8 +52,8 @@ If you operate multiple Bytebase replicas outside the bundled chart:
If your environment uses only the bundled Helm chart with its default topology:
-1. Run `helm upgrade` with the new Bytebase version or configuration.
-2. Wait for the single StatefulSet replica to become healthy.
+1. Run `helm upgrade` with the new Bytebase version or configuration. With `--wait` or `--atomic`, set `--timeout` above the expected migration time.
+2. Wait for the single StatefulSet replica to become ready. It stays unready while Bytebase migrates the metadata database, and the chart does not restart it.
3. Verify the updated version via `GET /v1/actuator/info`.
## After the upgrade
diff --git a/helm-charts/bytebase/Chart.yaml b/helm-charts/bytebase/Chart.yaml
index 8fc806897a..83bcc40a8f 100644
--- a/helm-charts/bytebase/Chart.yaml
+++ b/helm-charts/bytebase/Chart.yaml
@@ -1,6 +1,6 @@
apiVersion: v2
name: bytebase
-version: 1.1.6
+version: 1.1.7
description: Safe database schema change and version control for DevOps teams.
type: application
home: https://www.bytebase.com/
diff --git a/helm-charts/bytebase/README.md b/helm-charts/bytebase/README.md
index ff30acc5bf..7583742d08 100644
--- a/helm-charts/bytebase/README.md
+++ b/helm-charts/bytebase/README.md
@@ -97,6 +97,8 @@ helm -n <YOUR_NAMESPACE> \
upgrade bytebase-release bytebase-repo/bytebase
```
+Bytebase migrates its metadata database at startup and opens its port only after the migration finishes, which can take a long time on a large metadata database. The chart sets only a readiness probe on `/healthz`, so the pod stays unready during the migration instead of being restarted. If you pass `--wait` or `--atomic` to `helm upgrade`, set `--timeout` above the expected migration time. Helm's default is `5m`, and `--atomic` rolls the release back to the previous Bytebase version when it expires, which does not support the migrated metadata database.
+
## Parameters
| Parameter | Description | Default Value |
@@ -129,6 +131,9 @@ upgrade bytebase-release bytebase-repo/bytebase
| `bytebase.extraSecretMounts` | Additional Bytebase secret mounts. Defined as an array of volumeMount objects. | [] |
| `bytebase.extraVolumes` | Additional Bytebase volumes. Defined as an array of volume objects. | [] |
| `bytebase.podAnnotations` | Annotations added to the Bytebase pod. Useful for metrics scrapers. | {} |
+| `bytebase.readinessProbe.periodSeconds` | How often the readiness probe calls `/healthz`. Other probe timing fields such as `initialDelaySeconds` and `successThreshold` are also accepted. | 10 |
+| `bytebase.readinessProbe.timeoutSeconds` | Seconds before a single `/healthz` call times out. | 10 |
+| `bytebase.readinessProbe.failureThreshold` | Consecutive failed calls before the pod is marked unready and removed from the Service. | 3 |
**If you enable bytebase persistence, you should provide storageClass and storage to bytebase to request a PVC, or provide the already existed PVC by existingClaim.**
diff --git a/helm-charts/bytebase/templates/statefulset.yaml b/helm-charts/bytebase/templates/statefulset.yaml
index 5c5a5d984b..372a5f70cf 100644
--- a/helm-charts/bytebase/templates/statefulset.yaml
+++ b/helm-charts/bytebase/templates/statefulset.yaml
@@ -179,13 +179,16 @@ spec:
{{- if $resources }}
resources: {{- toYaml $resources | nindent 12 }}
{{- end }}
- livenessProbe:
+ # Bytebase opens this port only after metadata migrations finish, which can take a long
+ # time on a large metadata database. A liveness probe would restart the pod mid-upgrade,
+ # so readiness is the only probe.
+ readinessProbe:
httpGet:
path: /healthz
port: {{ $port }}
- initialDelaySeconds: 300
- periodSeconds: 300
- timeoutSeconds: 60
+ {{- with .Values.bytebase.readinessProbe }}
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
volumeMounts:
- mountPath: {{ $data }}
{{- if $persistenceExistingClaim }}
diff --git a/helm-charts/bytebase/values.yaml b/helm-charts/bytebase/values.yaml
index b6b4834ee9..04a2ad49e2 100644
--- a/helm-charts/bytebase/values.yaml
+++ b/helm-charts/bytebase/values.yaml
@@ -65,6 +65,13 @@ bytebase:
# cpu: 1000m
# memory: 1Gi
+ # -- Timing of the readiness probe on /healthz. Accepts any probe timing field:
+ # initialDelaySeconds, periodSeconds, timeoutSeconds, failureThreshold, successThreshold.
+ readinessProbe:
+ periodSeconds: 10
+ timeoutSeconds: 10
+ failureThreshold: 3
+
# -- Annotations added to the Bytebase pod. Useful for metrics scrapers and
# other tooling that discovers pods by annotation.
podAnnotations: {}