Import & Export YAML Configuration

The Zerops YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments.

YAML Configuration Basics

The Zerops YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways:

Using the GUI:
- For projects: In the Zerops dashboard, click on Import a project in the Projects section
- For services: Navigate to a project's details page and click Import services in the services section
Using the CLI: Run zcli project project-import for projects or zcli project service-import for individual services

Both methods provide straightforward ways to migrate or replicate infrastructure as needed.

This section provides a comprehensive example of an import YAML configuration file, allowing you to define and import a project and its services with environment variables.

# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # Project core package - LIGHT/SERIOUS
  corePackage: SERIOUS
  # List of project tags for filtering
  tags:
    - test
    - dev
  # Project-level environment variables
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
# ==== Define a list of services to import into the project ====
services:
  # REQUIRED. Name of your service
  - hostname: app
    # REQUIRED. Choose from list of supported technologies and their versions
    type: nodejs@22
    # HA or NON_HA mode
    mode: HA
    # Map of secret environment variables
    envSecrets:
      SECRET_KEY: <@generateRandomString(<32>)>
    # Environment variables defined in .env format (automatically creates secret envs)
    dotEnvSecrets: |
      APP_KEY=<@generateRandomString(<32>)>
      DB_PASSWORD=secure123
    # Object storage size in GB
    objectStorageSize: 2
    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-read-write
    # Define additional policy
    objectStorageRawPolicy:
    # One time build git repository
    buildFromGit: https://github.com/myorg/myapp
    # true or false
    enableSubdomainAccess: true
    # The higher the sooner the service is created
    priority: 1
    # Vertical autoscaling configuration object
    verticalAutoscaling:
      minCpu: 1
      maxCpu: 3
      # Choose SHARED or DEDICATED
      cpuMode: DEDICATED
      minRam: 1
      maxRam: 4
      minDisk: 1
      maxDisk: 10
      startCpuCoreCount: 2
      minFreeCpuCores: 0.5
      minFreeCpuPercent: 20
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
    # Minimum number of containers
    minContainers: 2
    # Maximum number of containers
    maxContainers: 6
    # List of shared storage services to connect to
    mount:
      - teststorage1
    # Full nginx config
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;

          server_name _;
          root /var/www;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }
    # Zerops.yaml configuration
    zeropsSetup: backendapi
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start
    # When set to true, enables overriding an existing runtime service with the same hostname and triggers a redeploy
    override: false
  # REQUIRED. Name of your other service
  - hostname: teststorage1
    type: shared-storage
    ...

Note

The example above is a general guideline; not all keys are valid for every service type. For technology-specific details, refer to the Create service page in the How To section of the Zerops documentation.

REQUIRED. If a parent object is defined, the key-value pair is required to be filled. All other key-value pairs are optional.

Project Configuration

The project configuration is used to define the project you want to import.

Usage

Field	Type	Description
project	object	REQUIRED, if a whole project is imported Only one project can be defined.
name	string, REQUIRED	The name of the new project. Duplicates are allowed.
description	string	Description of the new project.
corePackage	string	Core package of the new project. Values: LIGHT/SERIOUS (default LIGHT)
tags	list of strings	One or more string tags. Tags provide better orientation in projects.
envVariables	map[string]string	Project-level environment variables that are available to all services in the project.

Warning

The corePackage value can't be changed later. Make sure to choose a suitable core package for your project.

This example will create a project named project0 with serious core package and the description This project is an example only. The project will have two tags: test and dev, and two environment variables: LOG_LEVEL and API_VERSION:

# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # Project core package
  corePackage: LIGHT
  # List of project tags for filtering
  tags:
    - test
    - dev
  # Project-level environment variables
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1

Service Configuration

The service configuration defines one or more services to import into your project. Services are specified as an array under the services key, allowing you to configure multiple services in a single YAML file. You need at least one service and either an existing project to import into or a project defined in the YAML file.

The Service Configuration section is divided into multiple subsections for better organization:

Service Basic Configuration - Core parameters like hostname, type, mode, and environment variables
Service Vertical Autoscaling - CPU, RAM, and disk scaling settings
Service Horizontal Autoscaling - Container count scaling settings
Service Mount Shared Storage - Connecting to shared storage services
Service Nginx Configuration - Custom web server settings
Service zerops.yaml Configuration - Build and run configurations

#yamlPreprocessor=on
services:
  - hostname: app           # REQUIRED: Unique service identifier
    type: nodejs@22                 # REQUIRED: Service type and version
    mode: HA                        # HA or NON_HA mode (default: NON_HA)

    # Environment variables
    envSecrets:                     # Secret environment variables (blurred in GUI)
      SECRET_KEY: <@generateRandomString(<32>)>  # Generated random string
    dotEnvSecrets: |                # Environment vars in .env format
      APP_KEY=<@generateRandomString(<32>)>

    # Storage configuration
    objectStorageSize: 2            # Object storage size in GB
    objectStoragePolicy: public-read-write  # Predefined S3 bucket policy
    # Note: Typically you would use either objectStoragePolicy OR objectStorageRawPolicy, not both
    objectStorageRawPolicy: |       # Custom S3 bucket policy
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": "*",
            "Action": ["s3:GetObject"],
            "Resource": ["arn:aws:s3:::{{ .BucketName }}/*"]
          }
        ]
      }

    # Build and deployment
    buildFromGit: https://github.com/myorg/myapp  # Git repo for one-time build
    enableSubdomainAccess: true     # Enable public access via Zerops subdomain
    priority: 1                     # Higher priority services are created sooner
    override: true                  # When true, triggers redeploy of existing service

    # Vertical autoscaling
    verticalAutoscaling:
      minCpu: 1                     # Minimum number of virtual CPUs
      maxCpu: 3                     # Maximum number of virtual CPUs
      cpuMode: DEDICATED            # SHARED or DEDICATED CPU mode
      minRam: 1                     # Minimum RAM in GB
      maxRam: 4                     # Maximum RAM in GB
      minDisk: 1                    # Minimum disk space in GB
      maxDisk: 10                   # Maximum disk space in GB
      startCpuCoreCount: 2          # Initial CPU core count
      minFreeCpuCores: 0.5          # Min free CPU cores before scaling
      minFreeCpuPercent: 20         # Min free CPU percentage before scaling
      minFreeRamGB: 0.5             # Min free RAM in GB before scaling
      minFreeRamPercent: 20         # Min free RAM percentage before scaling

    # Horizontal autoscaling
    minContainers: 2                # Minimum number of containers (default: 1, max: 10)
    maxContainers: 6                # Maximum number of containers (max: 10)

    # Shared storage
    mount:                          # List of shared storage services to mount
      - teststorage1

    # Nginx configuration
    nginxConfig: |-                 # Custom nginx configuration
      server {
          listen 80 default_server;
          listen [::]:80 default_server;
          server_name _;
          root /var/www/public;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }

    # Zerops.yaml configuration
    zeropsSetup: backendapi          # Service setup name from zeropsYaml or repo
    zeropsYaml:                     # Full zerops.yaml configuration
      zerops:
        - setup: backendapi
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start

  # A second, simpler service example
  - hostname: teststorage1
    type: shared-storage

This example includes all possible configuration options for Zerops services. Not all options are required or applicable to every service type. The example shows two services in the same YAML file: a fully configured Node.js API service and a simpler static frontend service.

Service Basic Configuration

Field	Type	Description
services	list of objects, REQUIRED	At least one service is required.
hostname	string, REQUIRED	The unique service identifier. Limitations: duplicates in the same project forbidden maximum 25 characters, lowercase ASCII letters (a-z) or numbers (0-9) only
type	enum, REQUIRED	Specifies the service type and version. See supported types.
mode	enum	Values: HA / NON_HA (default NON_HA) Defines the operation mode of the service.
envSecrets	map[string]string	Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in Zerops GUI.
dotEnvSecrets	string (multiline)	Environment variables in .env file format that are automatically created as secret envs.
objectStorageSize	integer	Object storage size in GB.
objectStoragePolicy	enum	Values: private / public-read / public-objects-read / public-write / public-read-write / custom Select a predefined AWS S3 bucket access policy.
objectStorageRawPolicy	json	Define your own AWS S3 bucket access policy. See AWS docs for details. Use `{{ .BucketName }}` placeholder if you need to use bucket name in your custom policy rules.
buildFromGit	string (URL)	A URL of a Github or Gitlab repository used for a one-time build of your service.
enableSubdomainAccess	boolean	Default: `false` Set `true`, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.
priority	integer	Services are sorted before creation by priority in descending order, i.e. the higher the priority the sooner the service is created.
override	boolean	Default: `false` This only works for runtime services. The parameter allows you to replace an existing runtime service with the same hostname byt triggering a redeploy if the service already exists.

#yamlPreprocessor=on
services:
# REQUIRED: Name of your service
- hostname: app
  # REQUIRED: Choose from list of supported technologies and their versions
  type: nodejs@22
  # High-Availability or Non-High-Availability mode
  mode: HA
  # Map of secret environment variables
  envSecrets:
    SECRET_KEY: <@generateRandomString(<32>)>
  # Environment variables in .env format
  dotEnvSecrets: |
    APP_KEY=<@generateRandomString(<32>)>
  # Object storage size in GB
  objectStorageSize: 2
  # Choose object storage policy from a predefined list
  objectStoragePolicy: public-read-write
  # Define additional policy
  objectStorageRawPolicy:
  # One time build git repository
  buildFromGit: https://github.com/myorg/myapp
  # Enables public access via zerops.app subdomain
  enableSubdomainAccess: true
  # The higher the sooner the service is created
  priority: 1
  # When set to true, triggers a redeploy of an existing runtime service with the same hostname
  override: false

This yaml will create a nodejs@latest service named app in HA (High-Availability) mode with the following configurations:

Environment variables:
- From envSecrets: SECRET_KEY (requires yamlPreprocessor)
- From dotEnvSecrets: APP_KEY in .env format (requires yamlPreprocessor)
Object storage: 2GB with public-read-write policy
Git repository: https://github.com/zeropsio/recipe-nodejs
Public access enabled via Zerops subdomain
Priority: 1
Override existing service: false

The services object allows you to define one or more services in the same yaml file.

Caution

The yamlPreprocessor option in your project & service import YAML is required to generate random secret values, passwords, and public/private key pairs. For more information, see the yamlPreprocessor page.

Service Vertical Autoscaling

The vertical autoscaling configuration defines how the service can scale its resources vertically.

Field	Type	Description
minCpu	integer	Minimum number of virtual CPUs
maxCpu	integer	Maximum number of virtual CPUs
cpuMode	enum	Values: SHARED / DEDICATED
minRam	float	Minimum RAM in GB that each container of the service can scale down to.
maxRam	float	Maximum RAM in GB that each container of the service can scale up to.
minDisk	float	Minimum disk space in GB that each container of the service can scale down to.
maxDisk	float	Maximum disk space in GB that each container of the service can scale up to.
startCpuCoreCount	integer	Number of CPU cores with which each container starts.
minFreeCpuCores	float	Minimum number of unused CPU cores before a container starts scaling.
minFreeCpuPercent	float	Minimum percentage of unused CPU cores before a container starts scaling.
minFreeRamGB	float	Minimum unused memory in GB before a container starts scaling.
minFreeRamPercent	float	Minimum percentage of unused memory before a container starts scaling.

services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    enableSubdomainAccess: true
    verticalAutoscaling:
      minCpu: 1                     # Minimum number of virtual CPUs
      maxCpu: 3                     # Maximum number of virtual CPUs
      cpuMode: DEDICATED            # SHARED or DEDICATED CPU mode
      minRam: 1                     # Minimum RAM in GB
      maxRam: 4                     # Maximum RAM in GB
      minDisk: 1                    # Minimum disk space in GB
      maxDisk: 10                   # Maximum disk space in GB
      startCpuCoreCount: 2          # Initial CPU core count
      minFreeCpuCores: 0.5          # Min free CPU cores before scaling
      minFreeCpuPercent: 20         # Min free CPU percentage before scaling
      minFreeRamGB: 0.5             # Min free RAM in GB before scaling
      minFreeRamPercent: 20         # Min free RAM percentage before scaling

This yaml will create a service with the hostname app with php-nginx@8.4 runtime with HA High-Availability mode for vertical autoscaling:

CPU: 1-3 virtual CPUs in DEDICATED mode
RAM: 1-4 GB
Disk Space: 1-10 GB

Service Horizontal Autoscaling

The horizontal autoscaling configuration is used to define the horizontal autoscaling settings for the service.

Field	Type	Description
minContainers	integer	Minimum number of containers of the service. Default: 1, maximum value: 10
maxContainers	integer	Maximum number of containers of the service. Maximum value: 10

services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/zeropsio/recipe-php
    enableSubdomainAccess: true
    # Minimum number of containers
    minContainers: 2
    # Maximum number of containers
    maxContainers: 6

The minContainers and maxContainers parameters allow you to define the minimum and maximum number of containers for the service. The service will automatically scale between these values as needed.

Service Mount Shared Storage

The mount shared storage configuration defines which shared storage services should be mounted to the service.

Field	Type	Description
mount	list of strings	Mount shared storage to the service. `buildFromGit` must be filled.

services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    enableSubdomainAccess: true
    mount:
      - teststorage1

The mount: parameter allows you to mount a shared storage (which should be created inside the project) to the service.

Service Nginx Configuration

The nginx configuration defines the nginx settings for the service.

Field	Type	Description
nginxConfig	string (multiline)	Insert full nginx config.

#yamlPreprocessor=on
services:
  - hostname: app
    type: php-nginx@8.4
    enableSubdomainAccess: true
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;

          server_name _;
          root /var/www;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }

The nginxConfig: |- parameter allows you to specify a custom nginx configuration for the service.

Service zerops.yaml Configuration

The zeropsSetup and zeropsYaml parameters provide flexibility in how you define and use your service configurations. Both parameters are optional and work together in the following ways:

Field	Type	Description
zeropsSetup	string	Specifies which service setup to use. This should match a setup name found in either the `zeropsYaml` parameter (if provided) or the `zerops.yaml` file in the repository root. If not specified, defaults to the service hostname.
zeropsYaml	object	Contains the full zerops.yaml configuration. If provided, this will be used instead of looking for a `zerops.yaml` file in the repository.

services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    # Specify which setup to use from zerops.yaml
    zeropsSetup: backendapi
    # Full zerops.yaml configuration
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@18
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./dist
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start

How They Work Together

Neither parameter specified:
- The system looks for a zerops.yaml file in the repository root
- It searches for a setup with a name that matches the service hostname
Only zeropsSetup specified:
- The system looks for a setup with the specified name in the zerops.yaml file in the repository root
Only zeropsYaml specified:
- The system uses the provided YAML configuration instead of looking for a file in the repository
- It searches for a setup with a name that matches the service hostname
Both parameters specified:
- The system uses the provided zeropsYaml configuration
- It specifically looks for the setup named in zeropsSetup within that YAML

If the specified zeropsSetup does not exist in the available YAML configuration (either provided in zeropsYaml or found in the repository), the import will fail.

Export

Zerops provides the ability to export your existing projects and services as YAML configurations through the GUI. This feature is particularly useful for:

Creating backups of your project configurations
Replicating project or service setups across different environments
Sharing project templates with team members
Creating version-controlled infrastructure configurations

The exported YAML follows the same structure as the import YAML configuration detailed above. It will contain all the configuration parameters you've set for your project and services.

How to Export

Exporting a Single Service

Navigate to your service dashboard in the Zerops GUI, click the three-dot menu (⋮) in the top-right corner of the service card, and choose Export service as yaml.

Exporting an Entire Project

In the Zerops GUI, go to the project dashboard, click the three-dot menu (⋮) in the top-right corner of the project card, and select Export project as yaml.

Using Exported Configurations

The exported YAML files are compatible with:

The Zerops GUI import functionality
The zcli project project-import command
The zcli project service-import command (for single service exports)

This allows you to easily move configurations between environments or create new instances of your infrastructure.

Troubleshooting

Yaml Preprocessing

YAML Configuration Basics​

Project Configuration​

Usage​

Service Configuration​

Service Basic Configuration​

Service Vertical Autoscaling​

Service Horizontal Autoscaling​

Service Mount Shared Storage​

Service Nginx Configuration​

Service zerops.yaml Configuration​

How They Work Together​

Export​

How to Export​

Exporting a Single Service​

Exporting an Entire Project​

Using Exported Configurations​