feat(liquibase): add native Liquibase migration Job with wait-for-job support

[piotrlaczykowski]

What

Adds native Liquibase migration support. A chart declares a liquibase: block and gets a complete pre-start database migration:

Resource	Name	Hook weight
ConfigMap (changelog)	<fullname>-liquibase-changelog	-20
ConfigMap (migrations)	<fullname>-liquibase-migrations	-20
Secret (credentials)	<fullname>-liquibase-env	-20
Job	<fullname>-liquibase	-10

waitForIt defaults to true, so the Deployment's pods get the existing kubectl wait init container and will not start until the migration completes. No new RBAC code — waitFor.active gained a second trigger, which transitively brings ServiceAccount creation, token automounting, and the <fullname>-wait-for-jobs Role/RoleBinding.

Minimal usage:

liquibase:
  enabled: true
  database:
    urlTemplate: "jdbc:sqlserver://{host}:{port};database={name};"
    host: sql-server
    port: 1433
    name: MyStore
    userName: sa
    existingSecret:
      name: my-external-secret
  changelog:
    file: liquibase/changelog.xml
  migrations:
    paths: ["liquibase/migrations/*.sql"]

Why

Charts needing a migration before pod start currently hand-roll all of it: their own singular job: block, their own pod-updater RBAC, their own waitForEnabled flag, two ConfigMap templates, and a connection Secret template. The framework already had the hard part (jobs[].waitForIt and its init container + RBAC); what was missing was Liquibase-shaped — JDBC URL composition, credential plumbing, and ConfigMaps for the changelog and SQL. There was no ConfigMap template in the framework at all.

Notable decisions

Changelog and migration SQL come from the consuming chart's own files. Because a consuming chart passes its own root context into the library include, .Files.Get / .Files.Glob inside a framework template resolve against that chart's directory. Verified with a throwaway two-chart probe before designing around it. SQL stays as real files with real diffs; changelog.content / migrations.files are inline escape hatches.

The framework ships no knowledge of any JDBC driver. An earlier revision had a database.engine enum selecting a default port and URL template; it was dropped during review. A closed enum in a library chart's public API is a liability — every unlisted driver needs an escape hatch, and correcting an entry later silently changes behaviour for charts pinned to it. Baked-in templates also hid the connection string, so vendor-specific parameters (encrypt, trustServerCertificate, oracle.net.ssl_server_dn_match, pool/timeout options) couldn't be expressed and failed at migration time rather than render time.

Configuration is explicitly one of two, neither with a default: database.url (a literal JDBC URL, tpl-rendered, never parsed by the framework) or database.urlTemplate (named placeholders {host}, {port}, {name}). Common templates are documented as examples in values.yaml, not implemented as code.

The JDBC URL is a plain env var; only username/password are Secret-sourced. A connection target is not a credential, and keeping it in the pod spec makes kubectl describe job diagnostic. database.existingSecret suppresses the generated Secret entirely — the supported path for production credentials via ExternalSecret.

_job.yaml was refactored into seven shared partials (_job-partials.tpl) rather than duplicating ~120 lines of pod spec into the new Job. Rendered output of the test template chart is byte-identical before and after across five value combinations: default, CA-bundle enabled, VPA enabled, no-resources, and scheduling (nodeSelector/tolerations/podAnnotations/podLabels).

Validation

Eight fail-fast rules in _values-validation.tpl, each verified to fire. Three are worth calling out:

• A changelog.file path or a migrations.paths glob that resolves to nothing now fails rather than shipping an empty ConfigMap and a migration that silently does nothing. Both messages name .helmignore as the non-obvious cause.
• urlTemplate placeholders are named, not positional. Positional printf verbs were dropped during review: verb count is checkable, verb meaning is not, so jdbc:custom:%s@%s:%s written intending name/host/port silently produced a valid-looking wrong URL. A printf verb is now rejected outright with the rewrite shown; so are unknown placeholders ({database}) and templates with no placeholders at all.
• Every placeholder actually used must have its value set, and the message names which are missing. Unused placeholders impose no requirement.

Testing

• Test template chart exercises the feature with real liquibase/changelog.xml and liquibase/migrations/001_init.sql fixtures, so existing helm lint / ct lint / kubeconform CI covers the new templates.
• Two new CI regression steps: the migration Job must be referenced by the wait init container with its RBAC present and its ConfigMaps/Secret weighted ahead of it; and existingSecret must suppress the generated Secret.
• npm test passes (40/40) — the bidirectional values-contract guard required the values.yaml declaration and the first .Values.liquibase read to land in one commit.
• Chart README and plugin skill regenerated. Fixed one real bug found there: the engine comment's raw | characters broke the generated markdown table.

Not verified locally: kubeconform — curl is blocked in my environment. All 29 rendered documents were checked to parse as YAML with structural spot-checks (every volumeMount has a backing volume, env sources correct, ConfigMap keys correct). CI runs the real schema validation.

Not breaking

New opt-in key, enabled: false by default. The _job.yaml refactor is provably output-identical.

Design spec and implementation plan are included under docs/superpowers/.

[lwasak]

Looks good