Static

apps/docs/content/features/env-variables.mdx

@@ -1,6 +1,6 @@
 ---
 title: Environment Variables
-description: Learn how to use and manage environment variables in Zerops.
+description: Learn how to use, manage, and isolate environment variables in Zerops.
 ---
 
 import Image from '/src/components/Image';
@@ -44,7 +44,7 @@ Your application must be redeployed when updating environmental variables in `ze
 
 #### 2. Secret Variables
 
-For storing sensitive data you don't want in your source repository. They can be updated without redeployment (though services need to be restarted).
+For storing sensitive data you don't want in your source repository. They can be updated without redeployment (though services need to be reloaded).
 
 Secret variables can be managed through:
 
@@ -87,7 +87,7 @@ These variables can also be [referenced](#referencing-variables).
 
 Variables that apply across all services within a [project](/features/infrastructure#projects). These provide a way to share common configuration across services.
 
-They work similarly to service secret variables but at project scope - they're managed through the GUI and can be updated without redeployment (though services need to be restarted).
+They work similarly to service secret variables but at project scope - they're managed through the GUI and can be updated without redeployment (though services need to be reloaded).
 
 ### User-Defined Variables
 
@@ -98,7 +98,7 @@ You can set project-wide variables through:
 Access **Project environment variables** in your project detail to:
 - Add individual variables one by one
 - Edit individual variables
-- Use the bulk editor with .env format:
+- Use the bulk editor with .env format
 
 #### Import Configuration
 
@@ -114,7 +114,97 @@ project:
 
 ### System-Generated Variables
 
-Zerops automatically generates project-level variables containing that can be [referenced](#referencing-variables) from services.
+Zerops automatically generates project-level variables that can be [referenced](#referencing-variables) from services.
+
+## Environment Variable Isolation
+
+A security feature that controls the **visibility** of environment variables across services within a project.
+
+By default, Zerops isolates environment variables between services to enhance security and prevent unintended access to sensitive information. This isolation can be configured at both project and service levels.
+
+### Isolation Modes
+
+Zerops supports two isolation modes:
+
+<table className="w-full my-1.5">
+  <thead>
+    <tr>
+      <th className="w-fit">Mode</th>
+      <th className="w-fit">Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td className="w-fit whitespace-nowrap"><code>service</code></td>
+      <td className="w-full"><strong>Default mode.</strong> Variables are isolated to their respective services. Services can only access their own variables and must explicitly reference variables from other services.</td>
+    </tr>
+    <tr>
+      <td className="w-fit whitespace-nowrap"><code>none</code></td>
+      <td className="w-full"><i>Legacy mode.</i> All variables from all services are automatically shared and accessible via prefixing.</td>
+    </tr>
+  </tbody>
+</table>
+### Configuring Isolation
+
+#### Project-Level Isolation
+
+Zerops automatically creates the `envIsolation` project variable with the default value `service`. You only need to modify this if you want to disable isolation:
+
+```yaml title="import.yaml"
+project:
+  ...
+  envVariables:
+    envIsolation: none  # Disables isolation, sharing all variables
+```
+
+This can also be set through the Project Environment Variables section in the GUI.
+
+#### Service-Level Override
+
+Individual services can override the project-level isolation setting:
+
+```yaml title="import.yaml"
+services:
+  - hostname: db
+    ...
+    envSecrets:
+      envIsolation: none  # This service's variables will be visible to all services
+```
+:::tip
+You might set a database service to `envIsolation: none` to expose its connection details to other services, without having to manually reference them, while keeping the rest of your services isolated.
+:::
+
+### Accessing Variables Across Services
+
+#### With Isolation Enabled (`service` mode)
+
+When isolation is enabled, you must explicitly create reference variables to access variables from other services:
+
+```yaml title="zerops.yaml"
+# In the 'app' service:
+run:
+  envVariables:
+    # Create a local reference to the 'password' variable from the 'db' service
+    DB_PASSWORD: ${db_password}
+```
+
+This approach gives you complete control over which variables are shared between services.
+
+#### With Isolation Disabled (`none` mode)
+
+When isolation is disabled, variables are automatically available across all services with the service name prefix:
+
+```yaml
+# In any service, you can directly access:
+${db_password}  # Accesses the 'password' variable from the 'db' service
+```
+
+### Best Practices for Variable Isolation
+
+1. **Use Default Isolation**: Keep the default `service` isolation for enhanced security.
+2. **Explicit References**: Create explicit references only for variables that need to be shared.
+3. **Naming Conventions**: Use clear naming patterns for reference variables (e.g. `DB_PASSWORD` for a reference to `db_password`).
+4. **Service-Level Exceptions**: Use service-level isolation overrides sparingly and only for services that need to expose their variables widely.
 
 ## Variable Restrictions
 
@@ -153,17 +243,23 @@ envVariables:
 ```
 
 #### Across Services
-Prefix variables with their respective service name:
+
+How this works depends on your environment variable isolation setting:
+
+**With Isolation Enabled** (`service` mode - default)
+* Create an explicit reference in the destination service:
 ```yaml
-setup: dbtest
-  run:
-    envVariables:
-      connectionString: 127.0.0.1
+# In the 'app' service
+envVariables:
+  # Creating a reference to the 'connectionString' from 'dbtest' service
+  dbConnection: ${dbtest_connectionString}
+```
 
-setup: app
-  run:
-    envVariables:
-      dbConnection: ${dbtest_connectionString}
+**With Isolation Disabled** (`none` mode)
+* Variables from other services are automatically injected into the container and available using the service prefix format `servicename_variablename`:
+```yaml
+# In any container, you can directly access variables from other services:
+# ${dbtest_connectionString}
 ```
 
 #### Between Build and Runtime Environments
@@ -201,4 +297,37 @@ envVariables:
   name: ${projectName}-${hostname}  # Results in: devel-app
 ```
 
+## Environment Variable Examples
+
+### Variable Isolation Example
+
+Consider a project with three services: `api`, `db`, and `cache`:
+
+```yaml title="Project structure"
+project:
+  name: my-project
+services:
+  - hostname: api
+    envSecrets:
+      # Creating explicit references to needed variables
+      DB_CONNECTION: ${db_user}:${db_password}@${db_hostname}:${db_port}
+      CACHE_URL: ${cache_hostname}:${cache_port}
+  - hostname: db
+    envSecrets:
+      password: secureDbPassword
+      user: dbuser
+      port: 5432
+  - hostname: cache
+    envSecrets:
+      password: cacheServerPass
+      port: 6379
+```
+
+With this setup:
+- The `api` service can only access the specific `db` and `cache` variables it explicitly references
+- The `db` service cannot see any variables from `api` or `cache`
+- The `cache` service cannot see any variables from `api` or `db`
+
+If we changed the project's `envIsolation` to `none`, all services would be able to see all variables from all other services (prefixed with the service name).
+
 *Need help? Join our [Discord community](https://discord.gg/zeropsio).*