From 40ecd0f6e13036dc25c9c450be677df3e3bd01cc Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Thu, 13 Mar 2025 16:41:56 +1100 Subject: [PATCH 1/2] add environment variable information --- docs/reference/env.mdx | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/reference/env.mdx b/docs/reference/env.mdx index 17d666f48..073690f57 100644 --- a/docs/reference/env.mdx +++ b/docs/reference/env.mdx @@ -14,3 +14,33 @@ If you are running your project in the cloud, build, or the run environment, Nit | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NITRIC_STACK_ID | The Stack ID of the project. Example: `coolkat-gcp-4c0wg0hg` | | NITRIC_ENVIRONMENT | The Environment that the app is running on. The value can be either `cloud` (for deployed in the cloud), `run` (for stacks running in nitric run), or `build` (for stack code running during the deployment gathering phase). | + +## Application Environment Variables + +To use environment variables locally and in your deployed projects, you can create a file named `.env`. When running your project locally using `nitric start` the environment variables will be made available to you. When running your project using `nitric run` and `nitric up`, the service is built into an image with the environment variables added at build time. An `.env` file might look like this: + +```text label:.env +API_URL=http://this.is/a/test-url +``` + +If you wish to use an environment variable file that is in a different location, you can point to the file using the `--env-file` or `-e` flag. + +```bash +nitric start --env-file ./config/.env.local + +nitric up -e ./config/.env.cloud +``` + +## CI/CD Pipelines + +Environment variables will be pulled from a `.env` file same when deploying your projects in a CI/CD environment, however, most CI/CD platforms provide options for using sensitive values. You can take a look at our CI/CD guides [here](/guides?tags=CI/CD) to see individual recommendations for each platform's workflow configurations. + +## When should I use Secrets instead? + +You should use cloud secrets over environment variables for services when you are using sensitive values and/or you require dynamic secret rotation or updates. Beyond this, you should be using Cloud Secrets when: + +- **Your secret needs to be rotated dynamically**: Cloud secret managers support automatic rotation. This ensures your services always retrieve the latest secrets without redeployment. +- **You need access control & audit logging**: Cloud secret managers provide fine-grained access control (e.g., IAM policies) and track access logs, enhancing security and compliance. +- **Your secret contains sensitive configuration values**: Environment variables are often exposed in process lists, logs, or debugging tools. Secret managers keep them encrypted and only accessible at runtime. +- **Your secret is shared across multiple services**: If multiple services need access to the same credentials, cloud secrets prevent duplication and simplify management. +- **You want to avoid redeployments for secret changes**: Environment variables require redeployments to update secrets, whereas cloud secret managers allow dynamic retrieval at runtime. From b59bd52feb31e1e4a8c718e3fc59453598352d90 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com> Date: Fri, 14 Mar 2025 14:38:24 +1100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Jye Cusch --- docs/reference/env.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/env.mdx b/docs/reference/env.mdx index 073690f57..1f1f54b99 100644 --- a/docs/reference/env.mdx +++ b/docs/reference/env.mdx @@ -17,7 +17,7 @@ If you are running your project in the cloud, build, or the run environment, Nit ## Application Environment Variables -To use environment variables locally and in your deployed projects, you can create a file named `.env`. When running your project locally using `nitric start` the environment variables will be made available to you. When running your project using `nitric run` and `nitric up`, the service is built into an image with the environment variables added at build time. An `.env` file might look like this: +To use environment variables locally and in your deployed projects, you can create a file named `.env`. When running your project locally using `nitric start` the environment variables will be made available to your application. When running your project using `nitric run` and `nitric up`, the service is built into an image with the environment variables added at build time. An `.env` file might look like this: ```text label:.env API_URL=http://this.is/a/test-url @@ -33,7 +33,7 @@ nitric up -e ./config/.env.cloud ## CI/CD Pipelines -Environment variables will be pulled from a `.env` file same when deploying your projects in a CI/CD environment, however, most CI/CD platforms provide options for using sensitive values. You can take a look at our CI/CD guides [here](/guides?tags=CI/CD) to see individual recommendations for each platform's workflow configurations. +Environment variables will also be pulled from a `.env` file when deploying your projects in a CI/CD environment, however, most CI/CD platforms provide options for using sensitive values. You can take a look at our CI/CD guides [here](/guides?tags=CI/CD) to see individual recommendations for each platform's workflow configurations. ## When should I use Secrets instead? @@ -41,6 +41,6 @@ You should use cloud secrets over environment variables for services when you ar - **Your secret needs to be rotated dynamically**: Cloud secret managers support automatic rotation. This ensures your services always retrieve the latest secrets without redeployment. - **You need access control & audit logging**: Cloud secret managers provide fine-grained access control (e.g., IAM policies) and track access logs, enhancing security and compliance. -- **Your secret contains sensitive configuration values**: Environment variables are often exposed in process lists, logs, or debugging tools. Secret managers keep them encrypted and only accessible at runtime. +- **Your secret contains sensitive configuration values**: Environment variables may be exposed in process lists, logs, or debugging tools. Secret managers keep values encrypted and only accessible at runtime. - **Your secret is shared across multiple services**: If multiple services need access to the same credentials, cloud secrets prevent duplication and simplify management. -- **You want to avoid redeployments for secret changes**: Environment variables require redeployments to update secrets, whereas cloud secret managers allow dynamic retrieval at runtime. +- **You want to avoid redeployment for secret changes**: Environment variables require redeployment to update secrets, whereas cloud secret managers allow dynamic retrieval and updates at runtime.