Skip to content

Comments

Multi-environment config via named contexts#3547

Open
kichristensen wants to merge 4 commits intogetporter:mainfrom
kichristensen:multiEnvironmentConfig
Open

Multi-environment config via named contexts#3547
kichristensen wants to merge 4 commits intogetporter:mainfrom
kichristensen:multiEnvironmentConfig

Conversation

@kichristensen
Copy link
Contributor

What does this change

Adds kubectl-style multi-context support to the Porter config file. Users can define multiple named environments in a single config file and switch between them at runtime.

New schemaVersion: "2.0.0" format:

schemaVersion: "2.0.0"
current-context: default
contexts:
  - name: default
    config:
      namespace: dev
      default-storage: localdb
  - name: prod
    config:
      namespace: prod
      default-storage: proddb

Context selection (highest to lowest priority):

  1. --context prod flag
  2. PORTER_CONTEXT=prod env var
  3. current-context: field in the config file
  4. Falls back to a context named "default"

New commands:

$ porter config context list
* default
  prod

$ porter config context use prod
Switched to context "prod".

Legacy flat config files continue to work unchanged. Using --context with a legacy file is a hard error with a clear message.

What issue does it fix

Closes #3523

Notes for the reviewer

  • Context list/use use viper internally so they work with any supported config format (YAML, TOML, JSON, HCL)
  • ConfigContextUse does a targeted regex replace of the current-context: line to preserve Liquid template variables elsewhere in the file
  • The defaultConfigTemplate (used by porter config edit when no file exists) now generates the new versioned format

Checklist

  • Did you write tests?
  • Did you write documentation?
  • Did you change porter.yaml or a storage document record? Update the corresponding schema file.
  • If this is your first pull request, please add your name to the bottom of our Contributors list. Thank you for making Porter better! 🙇‍♀️

Add kubectl-style multi-context support to the Porter config
file using a new schemaVersion: "2.0.0" format. Users can
define multiple named contexts in a single config file and
select between them at runtime.

Changes:
- New config format: schemaVersion, current-context, contexts[]
- --context flag and PORTER_CONTEXT env var for context selection
- Context selection priority: flag > env var > current-context
  field in file > "default"
- Legacy flat format still supported; hard error if --context
  used with it
- porter config context list: list contexts, mark active one
- porter config context use <name>: update current-context
- ConfigContextList uses viper (format-agnostic: TOML/JSON/HCL)
- defaultConfigTemplate updated to new versioned format
- Integration tests + CI workflow jobs added

Signed-off-by: Kim Christensen <kimworking@gmail.com>
Adds `porter config migrate` to convert a legacy flat config
file to the multi-context format (schemaVersion: "2.0.0").

- Existing settings are wrapped under a "default" context
- Text-based transformation preserves Liquid template vars
- TOML/JSON/HCL files get a hard error with manual guidance
- No-op if file already uses the multi-context format
- Unit tests (4) and integration test added

Signed-off-by: Kim Christensen <kimworking@gmail.com>
New page: docs/configuration/multi-context.md covering
- config file format (schemaVersion 2.0.0)
- context selection priority (flag > env > current-context > default)
- porter config context list/use commands
- porter config migrate for upgrading legacy files

Updated configuration.md to link to the new page.

Signed-off-by: Kim Christensen <kimworking@gmail.com>
Signed-off-by: Kim Christensen <kimworking@gmail.com>
@kichristensen kichristensen marked this pull request as ready for review February 22, 2026 22:09
@kichristensen kichristensen requested a review from a team as a code owner February 22, 2026 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Handle multiple configurations natively

1 participant