Generate db_key_base as a list and keep an existing list

Rémy Coutablerequested to merge
rymai/db-key-base-list into master

What does this MR do?

Prepares the chart for rotatable db_key_base keys:

  • New installs now get db_key_base as a YAML list of one key, so that a key can be added later to rotate it. GitLab reads the value through Array(): the last key encrypts and every key decrypts, like the Active Record Encryption keys.
  • Existing installs keep their string. The shared-secrets job never converts one form into the other.
  • Fixes a list being mangled on upgrade. Before this change, the job rendered a list in the Rails secret inline as db_key_base: - key, with later entries at column 0. kubectl rejected that document and the shared-secrets job failed.

How:

  • In templates/shared-secrets/_manifest.tpl, db_key_base changes from shape: scalar to shape: list. Both backends already handle a list: they generate a list of one key when the field is missing, and keep any existing value. The Job renders a list with every entry indented. An existing string ends up on the line after the key, which is still the same YAML string.

Specs run the rendered merge in bash against a stubbed kubectl and cover a fresh install, an existing string, block and flow-style lists, and repeated upgrades. The three list cases fail on master. These specs need mikefarah yq v4, the same tool the Job's image uses. scripts/ci/install_spec_dependencies.sh now installs it (4.54.1, the version CNG pins) so the specs run in CI. They are skipped where it isn't installed.

Requires GitLab 19.5 or later. Chart 10.5 is already released, so this ships in chart 10.6. Until Phase 1.2 (https://gitlab.com/gitlab-org/gitlab/-/work_items/631579), Terraform::StateUploader and Ci::PipelineArtifactUploader passed the raw credential to OpenSSL::HMAC.digest, which raises on any list, even one with a single key. On GitLab master (19.5.0-pre), the credential is now only read through Array() in config/settings.rb.

Docs: rotation isn't documented yet, because GitLab support is still being implemented. doc/installation/secrets.md says so, and tells operators not to add keys to the list. The rotation runbook is tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/631762.

Related issues

Related to https://gitlab.com/gitlab-org/gitlab/-/work_items/631573 (the rotation docs are tracked separately, in https://gitlab.com/gitlab-org/gitlab/-/work_items/631762)

Author checklist

For general guidance, please follow our Contributing guide.

Required

For anything in this list which will not be completed, please provide a reason in the MR discussion.

  • Merge Request Title and Description are up to date, accurate, and descriptive.
  • MR targeting the appropriate branch.
  • MR has a green pipeline.
  • Documentation created/updated.
  • Tests added/updated.
  • Have you validated that your change works end-to-end on a real cluster deployment?
    • Describe how you did it in a comment.
  • Equivalent MR/issue for omnibus-gitlab opened. https://gitlab.com/gitlab-org/gitlab/-/work_items/631572
  • When ready for review, MR is marked as ready (not a draft) and assigned to a reviewer.

Reviewers checklist

🤖 Generated with Claude Code

Edited by Rémy Coutable

Merge request reports