diff --git a/applications/configuration-as-code/reference.mdx b/applications/configuration-as-code/reference.mdx index fd88740..e3f6deb 100644 --- a/applications/configuration-as-code/reference.mdx +++ b/applications/configuration-as-code/reference.mdx @@ -146,7 +146,7 @@ For sensitive values, use environment groups instead of hardcoding them in `port Optional -Names of environment groups to attach to the application. Environment groups must already exist in the Porter cluster where the app will be deployed. +Names of [environment groups](/applications/configure/environment-groups) to attach to the application. Environment groups are project-wide and must already exist before deploying. ```yaml envGroups: diff --git a/applications/configure/environment-groups.mdx b/applications/configure/environment-groups.mdx index 70c33e3..148413c 100644 --- a/applications/configure/environment-groups.mdx +++ b/applications/configure/environment-groups.mdx @@ -2,69 +2,168 @@ title: "Environment Groups" --- -An environment group (or env group for short) is a set of environment variables that are meant to be reused across multiple applications. For example, if all web services require a shared set of API and database keys, this could form a web-service environment group with all of those keys as a shared configuration. In this guide, we will explain how to create and use environment groups. +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 groups are stored in your own cluster as a Kubernetes Config Map - or a Kubernetes Secret. The data will be visible to any users or services with - access to your cluster, such as Porter. +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. -## Creating Environment Groups +## How Secrets Are Stored -You can create a new environment group in the “Env Groups” tab on the dashboard. +Environment group secrets are automatically synced to the secret manager of every cloud account linked to your project that has a running cluster: -![image](/images/other/env-group-tab.png) +- **AWS** — AWS Secrets Manager +- **GCP** — GCP Secret Manager +- **Azure** — Azure Key Vault -Clicking the “New Env Group” button will open a modal where you can enter the name of the environment group and the environment variables that should be included in the group. -You can add your environment variables by clicking the **Add Row** button or batch upload them via a .env file using the **Copy from File** button. +No secret data is stored on Porter's infrastructure. Secrets only exist in memory on Porter's servers momentarily during creation and updates. -![create-env-group](/images/other/env-group-create.png) +## Creating an Environment Group -## 🔒 Creating Secret Environment Variables +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. -Porter supports creating secret environment variables that will not be exposed after creation. At the moment, you must create an environment group in order to create secret environment variables. To create a secret environment variable, click on the lock icon next to the environment variable during creation of the environment variable: +You can also create environment groups from the CLI: -![create-env-group](/images/other/env-group-secrets.png) + +```bash Interactive +porter env create +``` -## How Secrets are Stored[](#how-secrets-are-stored "Direct link to heading") +```bash Non-Interactive +porter env create --name production-secrets +``` -All env group variables are stored **in your own cluster**, and not on Porter's infrastructure. The entire env group is stored as a Kubernetes [Config Map](https://kubernetes.io/docs/concepts/configuration/configmap/), which is meant for non-sensitive, unstructured data. When you create a secret environment variable, the ConfigMap will contain a reference to a Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret), which contains the secret data. This secret will be [injected into your container](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/) as it is mounted, and will not be exposed on the Porter dashboard after creation. To summarize: +```bash With Variables and Secrets +porter env create --name production-secrets \ + -v NODE_ENV=production -v LOG_LEVEL=info \ + -s DB_PASSWORD=secret -s API_KEY=sk-123 +``` + -- No env group data is stored on Porter's servers: it is all stored on your own cluster. -- **Non-sensitive data** in an env group will be read into memory on Porter's servers during deployment, and added directly to the deployment. -- **Sensitive data** in an env group will **not** be read into memory on Porter's servers during deployment, and are referenced as a secret during deployment. This sensitive data only exists in memory on Porter's infrastructure during creation/updating of the env group (**not** the deployment). +## Variables and Secrets -## Syncing Environment Groups to Applications[](#syncing-environment-groups-to-applications "Direct link to heading") +Environment groups support two types of values: -Environment groups have the capability to sync with applications, so when the environment variables are updated the synced applications are automatically restarted. -To sync a env group to an application either add it during creation of the app: +| 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 | -![sync-env-group](/images/other/env-group-sync.png) +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. -You can also navigate to the application and add the env group from the **Env Groups** tab and hit **Update app**: +## Files -![sync-env-group-tab](/images/other/env-group-sync-tab.png) +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: - - **Note:** Only a limit of 3 environment groups can be synced to an - application. If your use case requires syncing more than 3 please contact us. - +``` +/etc/secrets/ +``` + +## 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`: + +```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**. -When you subsequently update those env group variables from the **Env groups** tab, the applications will be restarted with the new variables. +### From the CLI -## Updating and Deleting Environment Groups[](#updating-and-deleting-environment-groups "Direct link to heading") +Use `porter env set` to add or update variables, and `porter env unset` to remove them: -To update your environment group, navigate back to the **Env Groups** tab, and click on the existing environment group to update. You can make changes to the env group here, and select the **Update** button when finished: + +```bash Set Variables +porter env set --group production-secrets -v LOG_LEVEL=debug -v FEATURE_FLAG=true +``` -![update-env-group](/images/other/env-group-update.png) +```bash Set Secrets +porter env set --group production-secrets -s DB_PASSWORD=new-password +``` -To delete the environment group, navigate to the **Settings** tab, and press the **Delete** button,: +```bash Remove Variables +porter env unset --group production-secrets -v OLD_VAR -v UNUSED_VAR +``` + +```bash Remove Secrets +porter env unset --group production-secrets -s ROTATED_KEY +``` + + +## Pulling Environment Variables Locally + +You can pull the contents of an environment group to your local machine for development: + + +```bash Print to stdout +porter env pull --group production-secrets +``` + +```bash Write to File +porter env pull --group production-secrets --file .env.local +``` + +```bash Variables Only +porter env pull --group production-secrets -v +``` + +```bash Secrets Only +porter env pull --group production-secrets -s +``` + - **Note:** You will not be able to delete an environment group if it is synced - to an application. Ensure you unsync the env group from all attached - applications in order to delete it. +The `--variables` (`-v`) and `--secrets` (`-s`) flags are mutually exclusive. If neither is specified, both variables and secrets are included in the output. -![delete-env-group](/images/other/env-group-delete.png) +## Listing Environment Groups + +To see all environment groups in your project: + +```bash +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](/standard/cli/command-reference/porter-env) CLI reference. diff --git a/mint.json b/mint.json index 10e29e0..ac25c89 100644 --- a/mint.json +++ b/mint.json @@ -90,11 +90,16 @@ } ] }, + { + "group": "Environment Groups", + "pages": [ + "applications/configure/environment-groups" + ] + }, { "group": "Configure", "pages": [ "applications/configure/basic-configuration", - "applications/configure/environment-groups", "applications/configure/autoscaling", "applications/configure/custom-domains", "applications/configure/zero-downtime-deployments", diff --git a/standard/cli/command-reference/porter-env.mdx b/standard/cli/command-reference/porter-env.mdx index ac58754..35c2ad4 100644 --- a/standard/cli/command-reference/porter-env.mdx +++ b/standard/cli/command-reference/porter-env.mdx @@ -2,39 +2,75 @@ title: 'porter env' --- -`porter env` contains commands for managing environment variables and secrets. +`porter env` contains commands for managing environment groups — project-wide sets of environment variables and secrets that can be shared across applications. ## Prerequisites - You've logged in to the Porter CLI after running [porter auth login](/standard/cli/command-reference/porter-auth) - You're connected to the correct project by running [porter config set-project](/standard/cli/command-reference/porter-config) -- You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config) --- -## Global Flags +## `porter env list` -These flags are available on all `porter env` subcommands: +List all environment groups in the current project. -| Flag | Short | Description | -|------|-------|-------------| -| `--app` | `-a` | Target application | -| `--group` | `-g` | Target environment group | -| `--target` | `-x` | Deployment target name | +**Usage:** +```bash +porter env list +``` + +Displays a table with each group's name, current version, and last updated time. + +--- + +## `porter env create` + +Create a new environment group. + +**Usage:** +```bash +porter env create [flags] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--name` | Environment group name (prompted interactively if omitted) | +| `--variables`, `-v` | Variables to set as key=value pairs | +| `--secrets`, `-s` | Secrets to set as key=value pairs | +| `--no-input` | Disable interactive prompts | + + +```bash Interactive +porter env create +``` + +```bash Non-Interactive +porter env create --name production-secrets +``` + +```bash With Variables and Secrets +porter env create --name production-secrets \ + -v NODE_ENV=production,LOG_LEVEL=info \ + -s DB_PASSWORD=secret,API_KEY=sk-123 +``` + -You must specify either `--app` or `--group`, but not both. +If an environment group with the same name already exists, the command will fail. Use `porter env set` to update an existing group. --- ## `porter env pull` -Pull environment variables from an application or environment group to your local machine. +Pull environment variables from an environment group to your local machine. **Usage:** ```bash -porter env pull [flags] +porter env pull [flags] ``` **Options:** @@ -46,24 +82,20 @@ porter env pull [flags] | `--secrets` | `-s` | Output only secrets (excludes variables) | -```bash From Application -porter env pull -a my-app -``` - -```bash From Environment Group -porter env pull -g production-secrets +```bash Print to stdout +porter env pull production-secrets ``` -```bash To File -porter env pull -a my-app -f .env.local +```bash Write to File +porter env pull production-secrets -f .env.local ``` ```bash Variables Only -porter env pull -a my-app -v +porter env pull production-secrets -v ``` ```bash Secrets Only -porter env pull -g my-env-group -s -f secrets.env +porter env pull production-secrets -s ``` @@ -75,11 +107,11 @@ By default, both variables and secrets are output together. Use `-v` or `-s` to ## `porter env set` -Set environment variables and secrets for an application or environment group. +Add or update variables and secrets in an environment group. **Usage:** ```bash -porter env set [flags] +porter env set [flags] ``` **Options:** @@ -88,49 +120,40 @@ porter env set [flags] |------|-------|-------------| | `--variables` | `-v` | Variables to set as key=value pairs | | `--secrets` | `-s` | Secrets to set as key=value pairs | -| `--skip-redeploys` | | Skip re-deploying apps linked to the environment group | -```bash Set App Variables -porter env set -a my-app -v KEY1=value1,KEY2=value2 -``` - -```bash Set Group Variables -porter env set -g my-env-group -v KEY1=value1 +```bash Set Variables +porter env set production-secrets -v LOG_LEVEL=debug,FEATURE_FLAG=true ``` ```bash Set Secrets -porter env set -g my-env-group -s API_KEY=secret123,DB_PASSWORD=pass456 +porter env set production-secrets -s API_KEY=sk-new-key ``` ```bash Set Both -porter env set -g my-env-group \ +porter env set production-secrets \ -v NODE_ENV=production,LOG_LEVEL=info \ -s DATABASE_URL=postgres://... ``` - -```bash Skip Redeploys -porter env set -g my-env-group -v KEY=value --skip-redeploys -``` -Use `-s/--secrets` for sensitive values like API keys and passwords. These are encrypted and not visible in logs. +Use `-s/--secrets` for sensitive values like API keys and passwords. Secrets are stored in your cloud provider's secret manager and are not visible after creation. -When updating an environment group, all apps linked to the group will be re-deployed unless you use `--skip-redeploys`. +When you update an environment group, all applications synced to it are automatically redeployed with the new values. --- ## `porter env unset` -Remove environment variables or secrets from an application or environment group. +Remove variables or secrets from an environment group. **Usage:** ```bash -porter env unset [flags] +porter env unset [flags] ``` **Options:** @@ -139,37 +162,75 @@ porter env unset [flags] |------|-------|-------------| | `--variables` | `-v` | Comma-separated list of variable names to remove | | `--secrets` | `-s` | Comma-separated list of secret names to remove | -| `--skip-redeploys` | | Skip re-deploying apps linked to the environment group | -```bash Unset Variables from App -porter env unset -a my-app -v KEY1,KEY2 +```bash Remove Variables +porter env unset production-secrets -v OLD_KEY,UNUSED_VAR +``` + +```bash Remove Secrets +porter env unset production-secrets -s ROTATED_KEY,OLD_SECRET +``` + +```bash Remove Both +porter env unset production-secrets -v VAR1 -s SECRET1 +``` + + + +When you update an environment group, all applications synced to it are automatically redeployed with the new values. + + +--- + +## Legacy Commands + +The following flag-based syntax is supported for managing app-level and cluster-level environment variables. These are legacy commands — for environment groups, use the positional argument syntax above. + +### Legacy Flags + +| Flag | Short | Description | +|------|-------|-------------| +| `--app` | `-a` | Target application | +| `--group` | `-g` | Target cluster environment group | +| `--target` | `-x` | Deployment target name | +| `--skip-redeploys` | | Skip re-deploying apps linked to the cluster environment group | + + +You must specify either `--app` or `--group`, but not both. + + + +```bash Pull from App +porter env pull --app my-app +``` + +```bash Pull from Cluster Env Group +porter env pull --group staging-config ``` -```bash Unset Secrets from App -porter env unset -a my-app -s API_KEY,DB_PASSWORD +```bash Set App Variables +porter env set --app my-app -v KEY1=value1,KEY2=value2 ``` -```bash Unset from Group -porter env unset -g my-env-group -v OLD_KEY,UNUSED_VAR +```bash Set Cluster Group Variables +porter env set --group my-env-group -v KEY1=value1 ``` -```bash Unset Both Variables and Secrets -porter env unset -g my-env-group -v VAR1 -s SECRET1 +```bash Unset App Variables +porter env unset --app my-app -v KEY1,KEY2 ``` ```bash Skip Redeploys -porter env unset -g my-env-group -v KEY --skip-redeploys +porter env set --group my-env-group -v KEY=value --skip-redeploys ``` - -When updating an environment group, all apps linked to the group will be re-deployed unless you use `--skip-redeploys`. - - --- -## Related Commands +## Related -- [porter app update](/standard/cli/command-reference/porter-app#porter-update) - Update app configuration -- [porter apply](/standard/cli/command-reference/porter-apply) - Deploy with environment variables in porter.yaml +- [Environment Groups](/applications/configure/environment-groups) — Overview of environment groups +- [porter.yaml Reference](/applications/configuration-as-code/reference) — `envGroups` field in porter.yaml +- [porter app](/standard/cli/command-reference/porter-app) — Application management commands +- [porter apply](/standard/cli/command-reference/porter-apply) — Deploy with porter.yaml