Skip to main content
Skip to main content

Environment Variables

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

On this page: Service Variables · Project Variables · Referencing Variables · Variable Isolation · Restrictions · Examples

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. All variables must follow the naming restrictions.

Note

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

2. Custom and Secret Variables​

Variables stored in Zerops, not in your source repository. They can be updated without redeployment, but the service has to be restarted to pick up the new values.

Each of these variables is either plain or sensitive:

  • Custom variables are plain.
  • Secret variables are sensitive. Their values are encrypted at rest with a per-project key and masked in the GUI and API responses. Inside the containers they are plain text, so your application reads them like any other variable.

You can create both kinds in the GUI, in import.yaml or through the API. In API requests, the sensitive flag decides which kind a variable is and defaults to false. See Reading sensitive values for who can see a secret value.

GUI Interface​

Navigate to service details and find Environment variables in the menu. The page has four sections:

In the Custom variables and Secret variables sections you can:

  • Add individual variables
  • Edit individual variables through the menu that appears on hover
  • Use the section's bulk editor to change multiple variables at once in .env format (see Editing several variables at once)

Secret values are masked. Revealing a value asks you to re-authorize, and so does loading secret variables into the bulk editor.

Runtime Secret Variables
Import Configuration​

Create custom and secret variables for a service with the vault attribute. Each entry is either a plain KEY: value pair, or an object with value and sensitive: true for a secret variable. See the complete import.yaml structure.

import.yaml
services:
- hostname: app
...
vault:
S3_ACCESS_KEY_ID:
value: your-secret-s3-key
sensitive: true
S3_ACCESS_SECRET:
value: your-s3-access-secret
sensitive: true
LOG_LEVEL: info

To paste variables in .env format, use dotEnvVariables for plain variables and dotEnvSecrets for secret variables. The envVariables and envSecrets attributes are deprecated but still accepted.

API​

The endpoints that create or update a single variable accept a sensitive flag, which defaults to false, and their responses include sensitive, editable and internal. When you create a service or trigger its pipeline, pass plain variables in envVarsFile and secret variables in envSecretsFile, both as .env text. The userDataEnvFile field is deprecated. To change several variables at once, see Editing several variables at once.

System-Generated Variables​

Zerops automatically generates variables based on service type.

These variables cannot be deleted and are listed in the Generated variables section of the environment variables page. Some are read-only (like hostname), while others can be edited (like PATH). Some are sensitive, such as a generated database password, and a sensitive system variable can't be changed to plain.

These variables can also be referenced.

Project Variables​

Variables that apply across the runtime services within a project. These provide a way to share common configuration across services.

Like custom and secret service variables, each project variable is either plain or sensitive, and sensitive values are encrypted and masked the same way. Project variables can be updated without redeployment, but services have to be restarted to pick up the new values.

important

Project variables are automatically inherited by all runtime services in the project — both in build and runtime environments. You do not need to reference them in your zerops.yaml.

Managed services don't receive project variables. A managed service's own variables, references to other services' variables and isolation work as usual.

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 to change multiple variables at once in .env format (see Editing several variables at once)

Import Configuration​

Create project variables with the vault attribute. Each entry is either a plain KEY: value pair, or an object with value and sensitive: true for a sensitive variable. See the complete import.yaml structure.

import.yaml
project:
...
vault:
LOG_LEVEL: info
API_VERSION: v1
SHARED_API_KEY:
value: your-api-key
sensitive: true

These variables are automatically available in all runtime services without any additional configuration. The envVariables and envSecrets attributes are deprecated but still accepted.

Through the API, project creation accepts envVariables (plain) and envSecrets (sensitive), each an array of {key, content} objects. Single project variables are created and updated with a sensitive flag that defaults to false.

System-Generated Variables​

Zerops automatically generates project-level variables that are also automatically available in all runtime services.

Overriding Project Variables​

If you need a different value for a specific service, you can override a project variable by defining a service-level variable with the same key. See Variable Precedence for details on how conflicts are resolved.

zerops.yaml
run:
envVariables:
LOG_LEVEL: debug # Overrides the project-level LOG_LEVEL for this service only

Environment Variable Isolation​

A security feature that controls the visibility of environment variables across services within a project. This affects how referencing variables across services works.

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

The envIsolation value is a space-separated list of rules. A service's own rules decide which other services can see its variables. The rules of the service doing the reading are never consulted, so a service can widen or narrow what it exposes, but never what it receives.

RuleDescription
serviceDefault. Only the service itself sees its variables. Other services must reference them explicitly.
noneEvery service in the project sees the variables, prefixed with the service hostname.
service@nameThe service with hostname name additionally sees the variables.
-service@nameThe service with hostname name never sees the variables, even when none is present.

Rule Evaluation Order​

When service reader asks for the variables of service owner, the rules of owner are checked in this order:

  1. -service@reader is present → hidden
  2. service@reader is present → visible
  3. none is present → visible
  4. Otherwise → hidden

Block rules always win over allow rules for the same service. A service always sees its own variables regardless of its rules, and explicit ${hostname_variable} references keep working in every mode.

Configuring Isolation​

Project-Level Isolation​

Zerops automatically creates the envIsolation project variable with the default value service. Every service inherits the project value unless it sets its own:

import.yaml
project:
envIsolation: service@zcp # The zcp service sees the variables of every other service

This can also be set through the Project Environment Variables section in the GUI.

Service-Level Override​

Individual services can replace the project-level value with their own. The values are not merged, the service value applies on its own:

import.yaml
project:
envIsolation: service@zcp
services:
- hostname: db
envIsolation: none # Everyone sees the db variables
- hostname: api
envIsolation: service # Nobody sees the api variables, not even zcp
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).

Common Combinations​

Single privileged reader (tooling, migrations, admin service):

envIsolation: service@zcp
  • ✅ The zcp service sees the variables of every service that inherits this value
  • ❌ Every other service stays isolated

Open project with one exception:

envIsolation: none -service@untrusted
  • ✅ All services see each other's variables
  • ❌ The untrusted service sees only its own variables and project variables

Selective exposure on one service:

services:
- hostname: db
envIsolation: service@api service@worker
  • ✅ The api and worker services see the db variables
  • ❌ Every other service must reference db variables explicitly

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.

When Variables Are Shared (none or service@name)​

When the owning service shares its variables, they are automatically available with the service name prefix:

# In any service the 'db' service shares variables with, you can directly access them:
${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. Grant, Don't Open: Prefer service@name for the one service that needs broad access over none, which exposes variables to every service.
  5. Service-Level Exceptions: Use service-level isolation overrides sparingly and only for services that need to expose their variables widely.

Referencing Variables​

You can reference other variables using the ${variable_name} syntax. This is used to reference service-level variables, not project variables (which runtime services already inherit automatically).

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
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 Reference Needed​

Project variables are automatically available in all runtime services. Do not use the ${...} syntax to reference them:

# ❌ Wrong - this shadows the project variable
envVariables:
PROJECT_NAME: ${PROJECT_NAME}

# ✅ Correct - just use the project variable directly in your app
# It's already available without any configuration

If a project variable is named LOG_LEVEL, your application can read it directly — you don't need to add anything to your zerops.yaml.

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​

Editing Several Variables at Once​

Custom and secret service variables and project variables can all be edited as a single .env file, with one KEY=value pair per line:

APP_KEY=abc123
DB_PASSWORD=secure123
MAIL_HOST=smtp.example.com

In the GUI, open the bulk editor of the Custom variables or Secret variables section on the service's Environment variables page, or in Project environment variables. Paste or edit the whole list and save it once, rather than adding or editing each variable separately.

Through the API, use the env file endpoints for service variables ↗ and project variables ↗. Each has one endpoint to read the variables as a file and one to write the edited file back. One request changes the whole set, while calling the single-variable endpoints once per variable starts a separate process for every variable. See the REST API reference for authentication and the full list of endpoints.

Variables are split into two groups, sensitive and non-sensitive, and the sensitive flag picks which group a request works with. A PUT sets that group to exactly what the file contains:

  • Keys in the file are created, or updated if they already exist in the group.
  • Keys in the group that are missing from the file are deleted.
  • If a key in the file already exists in the other group, the request fails.

Because missing keys are deleted, read the current file first, edit it, and send the whole file back. Reading sensitive values requires sudo mode. As with any change to these variables, restart the affected services to pick up the new values.

Reading Sensitive Values​

The value of a sensitive variable is only returned to a request in sudo mode:

  • In the GUI, you enter sudo mode by re-authorizing. The GUI asks you to when you reveal a secret value or load secret variables into the bulk editor.
  • An API token is in sudo mode if it was created with sudo: true. Creating such a token requires sudo mode. A token without sudo always gets REDACTED in place of sensitive values.

List and detail endpoints return REDACTED for a sensitive value unless the request is in sudo mode and the user's role isn't read-only. The read-only role never gets sensitive values. To reveal a single value, use the reveal endpoint for a service variable ↗ or a project variable ↗. Both require sudo mode.

Project and service exports write sensitive variables as value: REDACTED unless you request the values with reveal=true, which also requires sudo mode.

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 custom and secret variables
    • Build and runtime containers are separate environments

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
vault:
# Creating explicit references to needed variables
DB_CONNECTION:
value: ${db_user}:${db_password}@${db_hostname}:${db_port}
sensitive: true
CACHE_URL: ${cache_hostname}:${cache_port}
- hostname: db
vault:
password:
value: secureDbPassword
sensitive: true
user: dbuser
port: 5432
- hostname: cache
vault:
password:
value: cacheServerPass
sensitive: true
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). With service@api instead, only the api service would see the db and cache variables, and db and cache would stay isolated from each other.

Need help? Join our Discord community.