Add db migrate job for Gateway upgrades

[jchanbcbc]

Database Migration Job Support for Layer7 Gateway Operator

Overview

This PR introduces a pre-upgrade database migration job for the Layer7 Gateway Operator. It allows Liquibase schema migrations to run as a dedicated Kubernetes Job before Gateway pods start during an upgrade, reducing downtime risk and preventing schema conflicts. This feature requires Gateway 11.2.2 or higher.

---

What's New

Gateway Entrypoint — Schema Update Modes

The Gateway container (entrypoint.sh) now supports four explicit schema update modes via EXTRA_JAVA_ARGS:

Mode	Description
default	Gateway runs Liquibase migrations on startup (existing behavior)
skip	Gateway skips schema update entirely; assumes migrations were run externally
liquibase-only	Run Liquibase migrations and exit (used by the migration Job)
liquibase-only-with-unlock	Release the Liquibase DATABASECHANGELOGLOCK before migrating, then exit

Operator — Migration Job (spec.app.management.database.migrationJob)

A new opt-in migrationJob section in the Gateway CR spec:

management:
  database:
    migrationJob:
      enabled: true                    # opt-in; default false
      activeDeadlineSeconds: 300       # job timeout; default 5 minutes
      clearLocks: false                # set true to release stale Liquibase locks before migrating
      jdbcUrl: ""                      # optional override to by-pass db proxies, defaults to database.jdbcUrl

Job lifecycle and sequencing:

• When migrationJob.enabled: true, the operator creates a Kubernetes Job that runs Liquibase in liquibase-only (requiring Gateway 11.2.2 or higher) mode before the Gateway Deployment is allowed to proceed.
• The Gateway Deployment is blocked until the migration job succeeds. If the job fails, an error is logged with instructions and the Gateway remains in its current state — no automatic rollout to pods with an unmigrated schema.
• If the job's spec changes between kubectl apply calls (e.g. a corrected jdbcUrl, a new image, or a changed clearLocks flag), the operator automatically deletes and recreates the job rather than getting stuck on a stale run.
• Failed jobs require manual intervention: kubectl delete job <name> -n <namespace> to retry.

Automatic skip mode for Gateway pods:

• When migrationJob.enabled: true, the operator automatically injects -Dgateway.db.schema-update.mode=skip into EXTRA_JAVA_ARGS for the main Gateway pods. This prevents them from attempting their own Liquibase run, since the Job already handles it. Users do not need to set this manually.

JDBC URL handling:

• If migrationJob.jdbcUrl is explicitly set, the operator appends ?createDatabaseIfNotExist=false (using ? or & correctly based on whether query params already exist). This ensures that a misconfigured or mistyped URL fails fast rather than silently creating an unintended database.
• If migrationJob.jdbcUrl is not set, the main database.jdbcUrl from the ConfigMap is used as-is, preserving the existing createDatabaseIfNotExist=true behavior for fresh installs.

Diskless vs non-diskless config parity:

• In diskless mode (default): the Secret is exposed as env vars; migrationJob.jdbcUrl overrides the main JDBC URL via Kubernetes env precedence.
• In non-diskless mode (disklessConfig.disabled: true): the Secret is mounted as a node.properties file (matching the main Gateway deployment behavior); migrationJob.jdbcUrl is not used — node.properties wins, consistent with Helm behavior.

clearLocks field:

• When clearLocks: true, the job runs in liquibase-only-with-unlock mode, which releases any stale DATABASECHANGELOGLOCK before applying migrations. Useful for recovering from a previously aborted migration. Changing this field triggers automatic job replacement. Recommended to use kubectl patch with type=merge.

Optional liquibaseLogLevel:

• spec.app.management.database.liquibaseLogLevel sets the LIQUIBASE_LOG_LEVEL env var on both the migration job and Gateway pods for debugging.

---

Files Changed

Component	File	Change
Gateway container	entrypoint.sh	4-mode schema update logic
Helm chart	values.yaml, db-migration-job.yaml, README.md, release-notes.md	Migration job template and documentation
Operator CRD	api/v1/gateway_types.go	MigrationJob.ClearLocks, Database.LiquibaseLogLevel
Operator job builder	pkg/gateway/migration_job.go	Job spec with diskless/non-diskless handling, URL normalization
Operator reconciler	pkg/gateway/reconcile/migration_job.go	Job lifecycle, deployment blocking, spec-change detection
Operator ConfigMap	pkg/gateway/configmap.go	Auto-inject skip mode, LIQUIBASE_LOG_LEVEL
Operator controller	internal/controller/gateway/controller.go	Owns(&batchv1.Job{}) to watch Job status changes