Environment groups

Share environment variables and secrets across multiple applications using project-wide groups synced to AWS, GCP, or Azure secret managers

An environment group is a set of environment variables and secrets that can be shared across multiple applications. Environment groups are project-wide — they can be used across all clusters and cloud accounts within your project. For example, if all of your web services need a shared set of API keys and database credentials, you can create an environment group containing those values and sync it to each service.

Environment variables configured directly on an application always take precedence over values from an environment group. This override applies on a per-variable basis — if an app sets API_KEY=xyz and a synced environment group has API_KEY=abc, the app-level value (xyz) is used.

How Secrets Are Stored

Environment group secrets are automatically synced to the secret manager of every cloud account linked to your project that has a running cluster:

• AWS — AWS Secrets Manager
• GCP — GCP Secret Manager
• Azure — Azure Key Vault

No secret data is stored on Porter’s infrastructure. Secrets only exist in memory on Porter’s servers momentarily during creation and updates.

Sync Target Clusters

By default, an environment group’s secrets are synced to the secret manager of every cluster in your project, including any clusters added later. If you want to scope a group to a subset of clusters — for example, to keep production secrets out of a staging cluster — you can pick specific sync targets from the dashboard.

This feature is gated behind a project-level flag. If you don’t see the Sync target clusters section in the create form or settings tab, contact Porter support to enable it for your project.

Selecting Sync Targets

When creating or editing an environment group, the Sync target clusters section shows:

• A Sync to all clusters in this project toggle — enabled by default
• A row for each cluster in your project, with its cloud provider icon

To restrict the group to specific clusters, turn off Sync to all clusters in this project and check the clusters you want to sync to. Leaving the toggle on means the group will sync to every current cluster in the project, as well as any clusters added in the future.

Updating Sync Targets

You can change a group’s sync targets at any time from the Settings tab on the environment group’s page. Use the Save button in the Sync target clusters pane to apply changes. Porter diffs the new list against the existing targets and adds or removes clusters as needed — secret values are left untouched.

Creating an Environment Group

You can create a new environment group from the Env Groups tab on the Porter dashboard. Click New Env Group, enter a name, and add your variables and secrets.

You can also create environment groups from the CLI:

Interactive

porter env create

Variables and Secrets

Environment groups support two types of values:

Type	Description	Visibility
Variables	Non-sensitive configuration values (max 25 KB per value)	Visible in the dashboard and CLI after creation
Secrets	Sensitive values such as API keys, passwords, and tokens (max 25 KB per value)	Hidden after creation; stored in your cloud provider’s secret manager

When creating or updating an environment group, use the lock icon in the dashboard (or the -s flag in the CLI) to mark a value as a secret.

Files

Environment groups can also contain files for sensitive data such as certificates or configuration files. Files are managed through the Porter dashboard and are injected into your application’s container at the path:

/etc/secrets/<env-group-name>

Syncing Environment Groups to Applications

Environment groups can be synced to applications so that when the group is updated, all synced applications are automatically redeployed with the new values.

From the Dashboard

You can sync an environment group to an application during app creation or by navigating to the application’s Env Groups tab and adding the group. Click Update app to apply.

From porter.yaml

Add the envGroups field to your porter.yaml:

version: v2
name: my-app

envGroups:
  - production-secrets
  - shared-config

services:
  - name: web
    type: web
    run: npm start
    port: 3000
    cpuCores: 0.5
    ramMegabytes: 512

Environment groups listed in envGroups must already exist in the project before deploying.

Updating an Environment Group

When you update an environment group, all applications synced to it are automatically redeployed with the new values.

From the Dashboard

Navigate to the Env Groups tab, click the environment group you want to update, make your changes, and click Update.

From the CLI

Use porter env set to add or update variables, and porter env unset to remove them:

Set Variables

porter env set --group production-secrets -v LOG_LEVEL=debug -v FEATURE_FLAG=true

Pulling Environment Variables Locally

You can pull the contents of an environment group to your local machine for development:

Print to stdout

porter env pull --group production-secrets

The --variables (-v) and --secrets (-s) flags are mutually exclusive. If neither is specified, both variables and secrets are included in the output.

Listing Environment Groups

To see all environment groups in your project:

porter env list

This displays a table with each group’s name, current version, and last updated time.

Deleting an Environment Group

Environment groups can be deleted from the Settings tab on the environment group’s page in the dashboard.

You cannot delete an environment group that is synced to an application. Unsync the environment group from all applications before deleting it.

CLI Reference

For the full list of flags and options, see the porter env CLI reference.