Multi-environment config via named contexts

.github/workflows/porter-integration-pr.yml

@@ -39,6 +39,11 @@ jobs:
     uses: ./.github/workflows/integ-reuseable-workflow.yml
     with:
       test_name: cli_test
+  config_integration_test:
+    name: Config Integration Test
+    uses: ./.github/workflows/integ-reuseable-workflow.yml
+    with:
+      test_name: config_test
   connection_nix_integration_test:
     name: Connection Integration Test
     uses: ./.github/workflows/integ-reuseable-workflow.yml

.github/workflows/porter-integration-release.yml

@@ -32,6 +32,12 @@ jobs:
     with:
       test_name: cli_test
       registry: ${{inputs.registry}}
+  config_integration_test:
+    name: Config Integration Test
+    uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main
+    with:
+      test_name: config_test
+      registry: ${{inputs.registry}}
   connection_nix_integration_test:
     name: Connection Integration Test
     uses: getporter/porter/.github/workflows/integ-reuseable-workflow.yml@main

cmd/porter/config.go

@@ -15,10 +15,68 @@ func buildConfigCommands(p *porter.Porter) *cobra.Command {
 
 	cmd.AddCommand(buildConfigShowCommand(p))
 	cmd.AddCommand(buildConfigEditCommand(p))
+	cmd.AddCommand(buildConfigMigrateCommand(p))
+	cmd.AddCommand(buildConfigContextCommands(p))
 
 	return cmd
 }
 
+func buildConfigContextCommands(p *porter.Porter) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "context",
+		Short: "Context commands",
+		Long:  "Commands for managing porter configuration contexts.",
+	}
+
+	cmd.AddCommand(buildConfigContextListCommand(p))
+	cmd.AddCommand(buildConfigContextUseCommand(p))
+
+	return cmd
+}
+
+func buildConfigContextListCommand(p *porter.Porter) *cobra.Command {
+	return &cobra.Command{
+		Use:     "list",
+		Short:   "List configuration contexts",
+		Long:    "List all contexts defined in the porter configuration file. The active context is marked with *.",
+		Example: "  porter config context list",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return p.ConfigContextList(cmd.Context())
+		},
+	}
+}
+
+func buildConfigContextUseCommand(p *porter.Porter) *cobra.Command {
+	return &cobra.Command{
+		Use:     "use <name>",
+		Short:   "Set the current configuration context",
+		Long:    "Set the current-context in the porter configuration file.",
+		Example: "  porter config context use prod",
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return p.ConfigContextUse(cmd.Context(), args[0])
+		},
+	}
+}
+
+func buildConfigMigrateCommand(p *porter.Porter) *cobra.Command {
+	return &cobra.Command{
+		Use:   "migrate",
+		Short: "Migrate the config file to the multi-context format",
+		Long: `Migrate the porter config file from the legacy flat format to the
+multi-context format (schemaVersion: "2.0.0"). The existing settings are
+preserved under a context named "default".
+
+Only YAML config files are supported for automatic migration. For TOML,
+JSON, or HCL files, the required structure is printed so you can apply
+the changes manually.`,
+		Example: "  porter config migrate",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return p.ConfigMigrate(cmd.Context())
+		},
+	}
+}
+
 func buildConfigShowCommand(p *porter.Porter) *cobra.Command {
 	opts := porter.ConfigShowOptions{}
 

cmd/porter/main.go

@@ -222,6 +222,7 @@ Try our QuickStart https://porter.sh/quickstart to learn how to use Porter.
 	globalFlags := cmd.PersistentFlags()
 	globalFlags.StringVar(&p.Data.Verbosity, "verbosity", config.DefaultVerbosity, "Threshold for printing messages to the console. Available values are: debug, info, warning, error.")
 	globalFlags.StringSliceVar(&p.Data.ExperimentalFlags, "experimental", nil, "Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.")
+	globalFlags.StringVar(&p.Config.ContextName, "context", "", "Name of the configuration context to use. Defaults to the context named \"default\".")
 
 	// Flags for just the porter command only, does not apply to sub-commands
 	cmd.Flags().BoolVarP(&printVersion, "version", "v", false, "Print the application version")

docs/content/docs/configuration/configuration.md

@@ -57,7 +57,19 @@ Instead, use templates to inject environment variables or secrets in the configu
 Environment variables are specified with ${env.NAME}, where name is case-sensitive.
 Secrets are specified with ${secret.KEY} and case sensitivity depends upon the secrets plugin used.
 
-Below is an example configuration file in yaml:
+### Multiple environments
+
+Porter supports defining multiple named environments (contexts) in a single
+config file, similar to how `kubectl` handles multiple clusters.
+See [Multiple Configuration Environments](/docs/configuration/multi-context/) for details.
+
+### Flat config file (legacy)
+
+The flat format places all settings at the top level of the config file.
+This format is still supported but is considered legacy.
+Use `porter config migrate` to convert it to the multi-context format.
+
+Below is a full example in YAML:
 
 ```yaml
 # ~/.porter/config.yaml

docs/content/docs/configuration/multi-context.md

@@ -0,0 +1,148 @@
+---
+title: Multiple Configuration Environments
+description: Manage multiple Porter environments in a single config file using named contexts
+weight: 5
+---
+
+Porter supports multiple named configuration contexts in a single config file,
+similar to how `kubectl` handles multiple clusters.
+This lets you switch between environments — such as `dev`, `staging`, and `prod`
+— without maintaining separate config files.
+
+- [Config file format](#config-file-format)
+- [Selecting a context](#selecting-a-context)
+- [Managing contexts](#managing-contexts)
+  - [List contexts](#list-contexts)
+  - [Switch context](#switch-context)
+- [Migrating from the legacy format](#migrating-from-the-legacy-format)
+
+## Config file format
+
+The multi-context format requires `schemaVersion: "2.0.0"` at the top of the
+config file. All settings are placed under named contexts inside a `contexts`
+list, instead of at the top level.
+
+```yaml
+# ~/.porter/config.yaml
+schemaVersion: "2.0.0"
+
+# The context used when --context is not specified
+current-context: default
+
+contexts:
+  - name: default
+    config:
+      namespace: dev
+      default-storage: devdb
+      default-secrets-plugin: filesystem
+      storage:
+        - name: devdb
+          plugin: mongodb
+          config:
+            url: "mongodb://localhost:27017/porter"
+
+  - name: prod
+    config:
+      namespace: prod
+      default-storage: proddb
+      default-secrets-plugin: azure.keyvault
+      storage:
+        - name: proddb
+          plugin: mongodb
+          config:
+            url: "${secret.prod-db-connection-string}"
+      secrets:
+        - name: prodvault
+          plugin: azure.keyvault
+          config:
+            vault: "my-prod-vault"
+            subscription-id: "${env.AZURE_SUBSCRIPTION_ID}"
+```
+
+The `config` block inside each context entry accepts exactly the same settings
+as the legacy flat config format.
+See [Configuration](/docs/configuration/configuration/) for a full list of
+available settings.
+
+## Selecting a context
+
+Porter resolves the active context using the following priority order
+(highest to lowest):
+
+| Source | How to set |
+|---|---|
+| `--context` flag | `porter install --context prod` |
+| `PORTER_CONTEXT` environment variable | `export PORTER_CONTEXT=prod` |
+| `current-context` field in the config file | `porter config context use prod` |
+| Falls back to a context named `default` | (automatic) |
+
+```bash
+# Use the prod context for a single command
+porter install --context prod
+
+# Use the prod context for the rest of the shell session
+export PORTER_CONTEXT=prod
+porter install
+porter list
+```
+
+## Managing contexts
+
+### List contexts
+
+`porter config context list` prints all contexts defined in the config file.
+The currently active context is marked with `*`.
+
+```console
+$ porter config context list
+* default
+  prod
+  staging
+```
+
+The active context reflects the same priority order described above.
+Passing `--context` changes which entry is marked:
+
+```console
+$ porter config context list --context prod
+  default
+* prod
+  staging
+```
+
+### Switch context
+
+`porter config context use <name>` updates the `current-context` field in the
+config file so that subsequent commands use the specified context by default.
+
+```console
+$ porter config context use prod
+Switched to context "prod".
+
+$ porter config context list
+  default
+* prod
+  staging
+```
+
+## Migrating from the legacy format
+
+If you have an existing flat config file, run `porter config migrate` to
+convert it automatically.
+The command wraps your current settings in a context named `default` and adds
+the required `schemaVersion` header.
+
+```console
+$ porter config migrate
+Migrated config.yaml to multi-context format. Use 'porter config show' to review.
+```
+
+The migration is text-based, so template variables such as
+`${env.MY_VAR}` and `${secret.MY_SECRET}` are preserved exactly as written.
+
+Only YAML config files are supported for automatic migration.
+For TOML, JSON, or HCL files, `porter config migrate` prints the required
+structure so you can apply the changes manually.
+
+After migrating, verify the result with `porter config show` and add additional
+contexts as needed.

docs/content/docs/references/cli/archive.md

@@ -37,6 +37,7 @@ porter archive FILENAME --reference PUBLISHED_BUNDLE [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/build.md

@@ -61,6 +61,7 @@ porter build [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles.md

@@ -20,6 +20,7 @@ Commands for working with bundles. These all have shortcuts so that you can call
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_archive.md

@@ -37,6 +37,7 @@ porter bundles archive FILENAME --reference PUBLISHED_BUNDLE [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_build.md

@@ -61,6 +61,7 @@ porter bundles build [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_copy.md

@@ -42,6 +42,7 @@ porter bundles copy [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_create.md

@@ -24,6 +24,7 @@ porter bundles create [bundle-name] [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_explain.md

@@ -44,6 +44,7 @@ porter bundles explain REFERENCE [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_inspect.md

@@ -48,6 +48,7 @@ porter bundles inspect REFERENCE [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/bundles_lint.md

@@ -37,6 +37,7 @@ porter bundles lint [flags]
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/completion.md

@@ -31,6 +31,7 @@ porter completion bash > /usr/local/etc/bash_completions.d/porter
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```

docs/content/docs/references/cli/config.md

@@ -20,6 +20,7 @@ Commands for managing Porter's configuration file.
 ### Options inherited from parent commands
 
 ```
+      --context string         Name of the configuration context to use. Defaults to the context named "default".
       --experimental strings   Comma separated list of experimental features to enable. See https://porter.sh/configuration/#experimental-feature-flags for available feature flags.
       --verbosity string       Threshold for printing messages to the console. Available values are: debug, info, warning, error. (default "info")
 ```
@@ -32,6 +33,8 @@ Most commands require a Docker daemon, either local or remote.
 
 Try our QuickStart https://porter.sh/quickstart to learn how to use Porter.
 
+* [porter config context](/cli/porter_config_context/)	 - Context commands
 * [porter config edit](/cli/porter_config_edit/)	 - Edit the config file
+* [porter config migrate](/cli/porter_config_migrate/)	 - Migrate the config file to the multi-context format
 * [porter config show](/cli/porter_config_show/)	 - Show the config file