Skip to main content
Skip to main content
🚧 Work in Progress

Environment Variables

Zerops manages environment variables at two scopes: service level and project level. These variables are handled automatically without requiring .env files.

Service Variables​

Variables that are specific to individual services.

User-Defined Variables​

You can define service-level variables in two ways:

1. Build & Runtime Variables​

These variables are defined with envVariables attribute in the build or run section of your zerops.yaml file and are accessible within their respective containers.

zerops.yaml
...
build:
envVariables:
DB_NAME: db
DB_HOST: 127.0.0.1
DB_USER: db
DB_PASS: password
...
run:
envVariables:
DB_NAME: db
DB_HOST: 127.0.0.1
DB_USER: db
DB_PASS: password

See how to reference variables between services and between build and runtime environments.

Note

Your application must be redeployed when updating environmental variables in zerops.yaml.

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 reloaded).

Secret variables can be managed through:

GUI Interface​

Navigate to service details and find Environment variables in the menu. You can:

  • Add individual variables using the "Add secret variable" button
  • Edit individual variables through the menu that appears on hover
  • Use the bulk editor for managing multiple variables in .env format

Runtime Secret Variables

Import Configuration​

Create secret variables for a service with envSecrets attribute. See the complete import.yaml structure.

import.yaml
services:
...
envSecrets:
S3_ACCESS_KEY_ID: 'your-secret-s3-key'
S3_ACCESS_SECRET: 'your-s3-access-secret'

System-Generated Variables​

Zerops automatically generates variables based on service type.

These variables cannot be deleted and are always listed at the bottom of the environment variables page. Some are read-only (like hostname), while others can be edited (like PATH).

These variables can also be referenced.

Project Variables​

Variables that apply across all services within a project. 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 reloaded).

User-Defined Variables​

You can set project-wide variables through:

GUI Interface​

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

Import Configuration​

Create project variables with envVariables attribute. See the complete import.yaml structure.

import.yaml
project:
...
envVariables:
LOG_LEVEL: info
API_VERSION: v1

System-Generated Variables​

Zerops automatically generates project-level variables that can be referenced 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:

ModeDescription
serviceDefault mode. Variables are isolated to their respective services. Services can only access their own variables and must explicitly reference variables from other services.
noneLegacy mode. All variables from all services are automatically shared and accessible via prefixing.

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:

import.yaml
project:
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:

import.yaml
services:
- hostname: db
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.

Note

In import YAML, envIsolation can also be nested under envVariables/envSecrets. (If both are present, the nested version takes precedence).

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:

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:

# 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​

All environment variables must follow these restrictions:

Key​

  • Alphanumeric characters only (use _ to separate words)
  • Must be unique within their scope
  • Case-sensitive

Value​

  • ASCII characters only
  • No EOL characters

Variable Management​

Variable Precedence​

When the same environment variable key exists in multiple places, Zerops follows these precedence rules:

  1. Service-level variables take precedence over project variables
  2. Within service-level:
    • Build/runtime variables override secret variables
    • Build and runtime containers are separate environments

Referencing Variables​

You can reference other variables using the ${variable_name} syntax:

Within Same Service​

envVariables:
id: 42069
hostname: app
name: ${id}-${hostname} # Results in: 42069-app

Across Services​

How this works depends on your environment variable isolation setting:

With Isolation Enabled (service mode - default)

  • Create an explicit reference in the destination service:
# In the 'app' service
envVariables:
# Creating a reference to the 'connectionString' from 'dbtest' service
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:
# In any container, you can directly access variables from other services:
# ${dbtest_connectionString}

Between Build and Runtime Environments​

Build and runtime are two distinct environments in Zerops. Each environment can have its own set of variables, and you can use the same variable names in both environments since they are separate. Due to this separation, variables defined in one are not automatically accessible in the other.

To share variables between environments, you need to use specific prefixes:

  • Use RUNTIME_ prefix to access runtime variables during build
  • Use BUILD_ prefix to access build variables during runtime

Here's an example of zerops.yaml file showing how to reference a runtime variable during build:

zerops.yaml
build:
envVariables:
API_KEY: ${RUNTIME_API_KEY} # Using runtime variable during build
run:
envVariables:
API_KEY: "12345-abcde" # Referenced in build with RUNTIME_ prefix

Project Variables​

No prefix needed when referencing project variables:

import.yaml
project:
...
envVariables:
projectName: devel
zerops.yaml
envVariables:
id: 42069
hostname: app
name: ${projectName}-${hostname} # Results in: devel-app

Environment Variable Examples​

Variable Isolation Example​

Consider a project with three services: api, db, and cache:

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.