Yaml preprocessing
The yamlPreprocessor option in your project & service import YAML allows you to generate random secret values, passwords, and public/private key pairs for your secret environment variables.
How does it work?
The yamlPreprocessor=on is required as the first line in your import YAML to enable the preprocessor.
#yamlPreprocessor=on
project:
name: project
services:
- hostname: app
type: nodejs@latest
buildFromGit: https://github.com/example/app
enableSubdomainAccess: true
vault:
# yamlPreprocessor feat: generates a random 64 char and stores it
SECRET_KEY:
value: <@generateRandomString(<64>)>
sensitive: true
- hostname: db
type: postgresql@16
mode: HA
After you've added the yamlPreprocessor=on line, the preprocessor will be enabled and you can now utilize the functions.
How Preprocessing Works
The YAML script processing happens in two sequential steps. During the first turn (preprocessing), the system scans for Zerops import functions and modifiers, evaluates them, and replaces function calls with their results. All this data is stored in memory.
The second turn handles standard processing, where the system creates the imported project, instantiates all required services, and handles environment variables, including setting up any new ones as needed.
Syntax Reference
| Sequence | Description |
|---|---|
<@ | The identifier of the beginning of a function expression syntax. |
( | The identifier of the beginning of the function parameters. |
) | The identifier of the end of the function parameters. |
, | A function parameters delimiter. |
< | Identifier of the beginning of a string expression (without @). |
> | The identifier of the end of a string expression or a function expression syntax. |
| | The separator between a string or a function expression content and a modifier name. |
\ | Escaping character. |
\<>| | Characters that need to be escaped to print them out. |
All functions in the preprocessor return values as strings, regardless of the operation performed. This includes numeric operations, random generation, and variable manipulation.
Parameter Data Types
Functions generally support 2 types of parameters.
String expressions
- Value is enclosed in
<and>characters. - Spaces between
<and>are NOT trimmed. - When the value is passed as a function parameter, it's always a string.
Variable reference names
Variables are used to store and reuse values across your configuration. They can be created using functions like setVar and retrieved using getVar.
- Variable references are NOT enclosed in
<and>when used withgetVar - Variable names are case-sensitive
- Spaces before and after the reference name are trimmed
- Returns an error if the variable doesn't exist
All parameters are handled as strings internally. For functions that expect numbers (like generateRandomString), the string values are automatically converted to numbers during processing.
Nested Expressions
The preprocessor supports nested function and string expressions, allowing you to:
- Combine multiple functions
- Use function outputs as inputs for other functions
- Nest string expressions within other strings
- Create complex, multi-level expressions
Examples of Nesting with Environment Variables
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
vault:
NESTED_STRINGS:
value: <Base and <Nested> content>
sensitive: true
NESTED_FUNCTIONS:
value: <@generateRandomString(<@generateRandomInt(<20>, <50>)>)>
sensitive: true
EVEN_MORE_NESTING:
value: <@setVar(<refVarName>, <@generateRandomString(<@generateRandomInt(<20>, <30>)>)>)>
sensitive: true
Outputs of Nesting with Environment Variables
Escaping to Print Reserved Characters
Reserved characters \<>| have to be escaped using the \ backslash to print them out. It's mandatory to escape the \ character itself.
The YAML processing happens in two sequential phases:
- Preprocessing Phase: Evaluates functions, modifiers, and replaces them with results
- YAML Processing Phase: Creates project, services, and handles environment variables
Each phase processes escape characters, so backslashes need to be escaped twice:
- If you want to output a single backslash
\, you need to use four backslashes\\\\ - Example:
Input: FILE_PATH: value\\\\with\\\\backslashes
Output: FILE_PATH: value\with\backslashes
It means that if DIR: <\\\\> is used, the final value stored in the environment variable will be just \. The same is true for any value with backslashes, like SERVER: True\\\\False, where the stored result will be True\False.
Examples of Correct Function Expressions
# Function will receive one parameter as the string constant value of: 30
<@generateRandomString(<30>)>
# Function will receive two parameters as the string constant values of: 200 and 1000
<@generateRandomInt(<200>, <1000>)>
# It's possible to nest functions one into the other.
<@generateRandomString(<@generateRandomInt(<200>, <1000>)>)>
# Using commas inside a string constant passed as the parameter is possible.
# The passed value is stored as internal variable under the name: commentValue
<@setVar(<commentValue>, <By the way, this is the text passed over as a value.>)>
# Function will receive one parameter as the internal variable reference: commentValue
# Its value is returned as a string if such an internal variable exists. If not, an error returns.
<@getVar(commentValue)>
# Examples of function expressions with escaped characters:
\<@generateRandomString(30)\> # Output: <@generateRandomString(30)>
\<@generateRandomString(\<30\>)\> # Output: <@generateRandomString(<30>)>
\<@generateRandomInt(\<30\>, \<80\>)\> # Output: <@generateRandomInt(<30>, <80>)>
\<@generateRandomInt(\<30\>\, \<80\>)\> # Output: <@generateRandomInt(<30>, <80>)>
\<@generateRandomInt(<30>, <80>)\> # Output: <@generateRandomInt(30, 80)>
Environment variable reference might need to be used as a part of string expressions. From the parsing point of view on the pre-processing level, they have not been recognized as something special but just a regular string, and they will be transparently passed without any modification. The second standard parsing turn only evaluates them.
# The part ` {ITEM_VALUE` is taken as a regular text when storing a string value as an internal variable.
<@setVar(<commentValue>, <By the way, this ${ITEM_VALUE} is text passed over as a value.>)>
# The returned value will be exactly the same when retrieving the previously stored value.
<@getVar(<commentValue>)>
# The returned value will be: By the way, this {ITEM_VALUE} is text passed over as a value.
List of import functions
If you don't use the yamlPreprocessor=on line at the beginning of your import YAML script, the preprocessor will not be enabled and the functions will not work.
The type: nodejs@latest is just an example. The functions are available for all runtime types.
generateRandomString (length)
This function generates a random string of specified length using alphanumeric characters and some special characters (_, -, .). It's useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.
| Field | Details |
|---|---|
| Syntax: | <@generateRandomString(<10>)> |
| Limitation: | Length of the string should be an integer between 1 and 1024 characters. eg. <10>, <512>, <1024>. |
| Output: | hR5hS79H4p |
Usage in import YAML
Output of import YAML
generateRandomBytes (length)
This function generates requested amount of cryptographically random bytes. It is useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.
| Field | Details |
|---|---|
| Syntax: | <@generateRandomBytes(<10>)> |
| Limitation: | Length of the string should be an integer between 1 and 1024 characters. eg. <10>, <512>, <1024>. |
| Output: | hR5hS79H4p |
Usage in import YAML
Output of import YAML
generateRandomInt (min, max)
This function generates a random integer within a specified range (inclusive). It's particularly useful when you need random numeric values, like ports, timeouts, or any other configuration that requires random numbers within specific bounds.
| Field | Details |
|---|---|
| Syntax: | <@generateRandomInt(<200>, <1000>)> |
| Minimum: | Required minimum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903). |
| Maximum: | Required maximum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903). |
| Output: | 823 |
Usage in import YAML
Output of import YAML
pickRandom (...param)
| Field | Details |
|---|---|
| Syntax: | <@pickRandom(<640>, <800>, <1024>, <1280>, <1440>, <1920>)> |
| Parameters: | The required parameters from which the selection will be made. eg. <1101>, <800>, <1920>, etc. |
| Output: | 1024 |
This function randomly selects one value from a list of provided options. It's helpful when you want to randomly assign values from a predefined set, such as screen resolutions, configuration options, or any other scenario where you need random selection from specific choices.
Usage in import YAML
Output of import YAML
setVar (name, content)
This function stores a value in memory for later use and returns the stored value. It's particularly useful when you need to reuse the same generated value multiple times in your configuration, ensuring consistency across different environment variables.
| Field | Details |
|---|---|
| Syntax: | <@setVar(<plainPassword>, <@generateRandomString(<16>)>)> |
| Variable: | The required parameter of the internal variable name under which the provided content can be retrieved later using getVar function. The chosen name is case-sensitive. eg. <varName>, <plainPassword>, etc |
| Content: | Any text you want to be stored, including composition using functions. Already existing variable with the same name is overwritten. |
| Output: | N4KdtM41WskS74wx |
Usage in import YAML
Output of import YAML
getVar (name)
This function retrieves a previously stored value from memory. It works in conjunction with setVar and other storage functions to access values that were generated or stored earlier in the configuration process. eg. plainPassword
| Field | Details |
|---|---|
| Syntax: | <@getVar(plainPassword)> |
| Variable: | The required parameter of the internal variable name that is case-sensitive. The parameter is used as a reference, so it MUST NOT be enclosed in < and >. eg. (plainPassword), (varName), etc |
| Output: | N4KdtM41WskS74wx |
Usage in import YAML
Output of import YAML
generateRandomStringVar (name, length)
This function combines the functionality of generateRandomString and setVar. It generates a random string and automatically stores it under a specified variable name for later use.
The output contains only a random combination of alphanumeric characters (a-zA-Z0-9) and select special characters (_, -, .).
| Field | Details |
|---|---|
| Syntax: | <@generateRandomStringVar(<plainPassword>, <10>)> |
| Variable: | The required parameter of the internal variable name under which the provided content can be retrieved later using getVar function. The chosen name is case-sensitive. eg. <plainPassword>, <varName>, etc |
| Limitation: | Required length of the string to be generated in characters (maximum allowed value is 1024). |
| Output: | hR5hS79H4p |
Usage in import YAML
Output of import YAML
generateJWT (tokenSecret, jsonPayload)
This function generates a JWT (JSON Web Token) signed by HS256 algorithm using provided secret and payload. The payload MUST be a valid JSON value. Default values for iss and iat are set to zerops and current timestamp respectively.
| Field | Details |
|---|---|
| Syntax: | <@generateJWT(<tokenSecret>, <jsonPayload>)> |
| Token Secret: | The required secret (string) used to sign your JWT. |
| JSON Payload: | The required payload part of the JWT (string) in JSON format. |
| Output: | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3Mjkw Njk4NTcsImlzcyI6Inplcm9wcyJ9.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACb jio |
Usage in import YAML
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
vault:
# Using a fixed secret string
JWT_FIXED:
value: <@generateJWT(<fixedSecretString>, <{"role":"admin","exp":1798761600}>)>
sensitive: true
# Using an empty payload
JWT_EMPTY:
value: <@generateJWT(<fixedSecretString>, <{}>)>
sensitive: true
# Generate and store a random secret, then use it
JWT_RANDOM:
value: <@generateJWT(<@generateRandomStringVar(<jwtSecretKey>, <32>)>, <{"role":"admin","exp":1798761600}>)>
sensitive: true
# Use a previously stored secret
JWT_STORED:
value: <@generateJWT(<@getVar(jwtSecretKeyVar)>, <{"role":"admin","exp":1798761600}>)>
sensitive: true
Output of import YAML
JWT_FIXED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio
JWT_EMPTY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjkwNjk4NTcsImlzcyI6Inplcm9wcyJ9.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio
JWT_RANDOM: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.ksbck_HQv44YXbqJk6lDrGFYTq3nmLydFIe0Xlejk5Q
JWT_STORED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.O0RaXzGFwj2t8P2kc4nU4PfuI43-dAuAl2d0T1uUlEE