Skip to content

Migrating package values for Big Bang 4.0

Big Bang 4.0 moves built-in package configuration from top-level and addons.<name> paths into packages.<name>. Starting with Big Bang 3.32, you can adopt this structure before upgrading by setting:

packageConfiguration:
  version: v1

This guide covers only that package-path migration. The script does not migrate other deprecated Big Bang settings, child-chart values, or the upcoming bb-common subchart values changes. Follow the applicable release notes for those migrations.

Use this guide to choose and run a migration workflow. For complete option semantics, safeguards, and troubleshooting, see the Package Values Migration Script Reference.

Requirements

Install:

SOPS-encrypted inputs also require sops and access to the document’s master keys. Authentication is inherited from the environment, such as AWS_PROFILE for AWS KMS.

Choose a workflow

Input Migration workflow
One plaintext values file Run the plaintext script with its default behavior.
Multiple plaintext files that can become one file Pass every file in Helm order and write one consolidated output.
Values sources that must remain separate Choose one primary source to own packageConfiguration.version: v1; use --omit-package-configuration on every secondary source.
Decrypted Kubernetes Secret Use the plaintext script with --secret-key.
SOPS-encrypted Kubernetes Secret Use the SOPS wrapper.

For Big Bang 3.x, designate one source to own packageConfiguration.version: v1, and always preserve the order in which Helm or Flux applies values. Later sources override earlier sources.

Migrate plaintext values

Write a migrated copy while leaving the input unchanged:

scripts/migrate-values-3-to-4.sh \
  --output values-4.x.yaml values.yaml

To replace one input, use --in-place. The command first creates values.yaml.bak and refuses to overwrite an existing backup:

scripts/migrate-values-3-to-4.sh --in-place values.yaml

Consolidate layered plaintext values

Pass files in the same order used by Helm. The script composes them first, applies later-file precedence, and writes one migrated document:

scripts/migrate-values-3-to-4.sh \
  --output values-4.x.yaml \
  base.yaml environment.yaml secrets.yaml

Do not consolidate decrypted credentials into a file that will be committed.

Keep values sources separate

Migrate the primary source normally:

scripts/migrate-values-3-to-4.sh \
  --output values-4.x.yaml values.yaml

Migrate each secondary source with the omission option:

scripts/migrate-values-3-to-4.sh \
  --omit-package-configuration \
  --output tests-4.x.yaml tests.yaml

Use this option only when another source in the same Big Bang 3.x release supplies version v1.

Migrate values in Kubernetes Secrets

Decrypted Secret

Use --secret-key when a decrypted Kubernetes Secret stores values under stringData or base64-encoded data:

scripts/migrate-values-3-to-4.sh \
  --secret-key values.yaml \
  --output environment-4.x.yaml environment.yaml

Add --omit-package-configuration when the Secret is a secondary values source. Do not use the plaintext command on a document that still contains SOPS metadata.

SOPS-encrypted Secret

The SOPS wrapper migrates and re-encrypts the selected values payload:

AWS_PROFILE=development \
  scripts/migrate-sops-values-3-to-4.sh \
  --output environment-4.x.enc.yaml environment.enc.yaml

For a secondary encrypted source:

AWS_PROFILE=development \
  scripts/migrate-sops-values-3-to-4.sh \
  --omit-package-configuration \
  --output secrets-4.x.enc.yaml secrets.enc.yaml

The embedded key defaults to values.yaml. See the SOPS command reference for custom keys, output modes, and security behavior.

Review and validate

Before committing migrated values:

  1. Review every moved package and any expanded anchors.
  2. Confirm exactly one separately stored source owns packageConfiguration.version: v1.
  3. Confirm the sources remain in their original Helm or Flux order.
  4. Rerun the same migration command with the same options; the output should be unchanged.
  5. Render all migrated plaintext values in their effective order.

For one consolidated output:

helm template bigbang ./chart -f values-4.x.yaml >/dev/null

For separate plaintext sources:

helm template bigbang ./chart \
  -f values-4.x.yaml \
  -f tests-4.x.yaml \
  >/dev/null

For encrypted sources, decrypt and extract the values into a protected temporary location for review and rendering. Never commit plaintext credentials, private keys, license data, or production endpoints.

The migration is idempotent when rerun with the same options. The script also expands and reports YAML anchors. Review the technical reference for precedence, ordering, anchor handling, refusal conditions, and output guarantees.

Keep packageConfiguration.version: v1 in the primary migrated configuration when upgrading. Big Bang 4.x retains it as the unified package contract.