Import YAML Reference

The Zerops Import YAML provides a powerful way to define your infrastructure as code. You can create or replicate entire projects and services using a declarative YAML configuration file.

Import Methods

You can import configurations in two ways: Using the GUI:

For projects: Click Import a project in the Projects section of the Zerops dashboard
For services: Navigate to a project’s details page and click Import services

Using the CLI:

zcli project project-import <importYamlPath> - Import entire project
zcli project service-import <importYamlPath> - Import services into existing project

File Structure

The import YAML consists of two main sections:

# Project definition (optional, required for project import)
project:
  name: my-project
  description: "Project description"
  corePackage: LIGHT
  tags:
    - production
  envVariables:
    LOG_LEVEL: info

# Services definition (required)
services:
  - hostname: app
    type: nodejs@22
    mode: HA
    ...

Project Configuration

project

object

Define a project to import. Required when importing a whole project, omitted when importing services into an existing project.

project.name

string

required

The name of the new project. Duplicates are allowed.

project:
  name: my-project

project.description

string

Description of the new project.

project:
  description: "Production environment for my application"

project.corePackage

string

default:"LIGHT"

Core package of the new project.Values:

LIGHT - Lightweight Core (default)
SERIOUS - Serious Core

project:
  corePackage: SERIOUS

The corePackage can be upgraded from Lightweight to Serious later, but cannot be downgraded. Upgrades involve a brief service disruption and are partially destructive (logs/statistics are lost). Learn more about the core upgrade process.

project.tags

string[]

One or more tags for better project organization and filtering.

project:
  tags:
    - production
    - api
    - customer-facing

project.envVariables

object

Project-level environment variables that are available to all services in the project.

project:
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
    REGION: us-east-1

Service Configuration

The services section defines one or more services to import into your project.

services

array

required

List of services to create. At least one service is required.

services:
  - hostname: app
    type: nodejs@22
    ...
  - hostname: db
    type: postgresql@16
    ...

Service Basic Configuration

services[].hostname

string

required

The unique service identifier within the project.Limitations:

No duplicates in the same project
Maximum 25 characters
Lowercase ASCII letters (a-z) or numbers (0-9) only

services:
  - hostname: api

services[].type

string

required

Specifies the service type and version.See supported service types for available options.

services:
  - hostname: app
    type: nodejs@22

services[].mode

string

default:"NON_HA"

Operation mode of the service.Values:

NON_HA - Non-High-Availability (default)
HA - High-Availability

services:
  - hostname: app
    mode: HA

services[].envSecrets

object

Environment variables that are blurred by default in the Zerops GUI. Can be edited or deleted later.

#yamlPreprocessor=on
services:
  - hostname: app
    envSecrets:
      SECRET_KEY: <@generateRandomString(<32>)>
      API_TOKEN: my-secret-token

The yamlPreprocessor directive enables functions like generateRandomString. See yamlPreprocessor documentation.

services[].dotEnvSecrets

string

Environment variables in .env file format that are automatically created as secret environment variables.

#yamlPreprocessor=on
services:
  - hostname: app
    dotEnvSecrets: |
      APP_KEY=<@generateRandomString(<32>)>
      DB_PASSWORD=secure_password
      JWT_SECRET=<@generateRandomString(<64>)>

services[].objectStorageSize

number

Object storage size in GB.

services:
  - hostname: app
    objectStorageSize: 10

services[].objectStoragePolicy

string

Select a predefined AWS S3 bucket access policy.Values:

private - No public access
public-read - Public read access
public-objects-read - Public read access to objects only
public-write - Public write access
public-read-write - Public read and write access
custom - Use custom policy defined in objectStorageRawPolicy

services:
  - hostname: app
    objectStoragePolicy: public-read

services[].objectStorageRawPolicy

string

Define a custom AWS S3 bucket access policy. See AWS documentation for details.Use {{ .BucketName }} placeholder to reference the bucket name in your policy.

services:
  - hostname: app
    objectStorageRawPolicy: |
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": "*",
            "Action": ["s3:GetObject"],
            "Resource": ["arn:aws:s3:::{{ .BucketName }}/*"]
          }
        ]
      }

services[].buildFromGit

string

URL of a GitHub or GitLab repository for a one-time build of your service.

services:
  - hostname: app
    buildFromGit: https://github.com/myorg/myapp

services[].enableSubdomainAccess

boolean

default:false

Enable public access to your service via a Zerops subdomain. Not recommended for production use.

services:
  - hostname: app
    enableSubdomainAccess: true

services[].priority

number

Services are sorted before creation by priority in descending order. Higher priority services are created first.

services:
  - hostname: db
    priority: 10
  - hostname: app
    priority: 5

services[].override

boolean

default:false

For runtime services only. When set to true, replaces an existing service with the same hostname and triggers a redeploy.

services:
  - hostname: app
    override: true

Service Vertical Autoscaling

Configure how services scale their resources vertically.

services[].verticalAutoscaling

object

Vertical autoscaling configuration for the service.

services:
  - hostname: app
    verticalAutoscaling:
      minCpu: 1
      maxCpu: 3
      cpuMode: DEDICATED
      minRam: 1
      maxRam: 4
      minDisk: 1
      maxDisk: 10

services[].verticalAutoscaling.minCpu / maxCpu

services[].verticalAutoscaling.minCpu

number

Minimum number of virtual CPUs.

services[].verticalAutoscaling.maxCpu

number

Maximum number of virtual CPUs.

services[].verticalAutoscaling.cpuMode

string

CPU allocation mode.Values:

SHARED - Shared CPU cores
DEDICATED - Dedicated CPU cores

verticalAutoscaling:
  cpuMode: DEDICATED

services[].verticalAutoscaling.minRam / maxRam

services[].verticalAutoscaling.minRam

number

Minimum RAM in GB.

services[].verticalAutoscaling.maxRam

number

Maximum RAM in GB.

services[].verticalAutoscaling.minDisk / maxDisk

services[].verticalAutoscaling.minDisk

number

Minimum disk space in GB.

services[].verticalAutoscaling.maxDisk

number

Maximum disk space in GB.

services[].verticalAutoscaling.startCpuCoreCount

number

Number of CPU cores with which each container starts.

services[].verticalAutoscaling.minFreeCpuCores

number

Minimum number of unused CPU cores before a container starts scaling.

services[].verticalAutoscaling.minFreeCpuPercent

number

Minimum percentage of unused CPU cores before a container starts scaling.

services[].verticalAutoscaling.minFreeRamGB

number

Minimum unused memory in GB before a container starts scaling.

services[].verticalAutoscaling.minFreeRamPercent

number

Minimum percentage of unused memory before a container starts scaling.

Service Horizontal Autoscaling

Configure the number of containers for the service.

services[].minContainers

number

default:1

Minimum number of containers. Maximum value: 10.

services:
  - hostname: app
    minContainers: 2

services[].maxContainers

number

Maximum number of containers. Maximum value: 10.

services:
  - hostname: app
    maxContainers: 6

Service Mount Shared Storage

services[].mount

string[]

List of shared storage services to mount. Requires buildFromGit to be set.

services:
  - hostname: app
    buildFromGit: https://github.com/myorg/myapp
    mount:
      - storage1
      - storage2

Service Nginx Configuration

services[].nginxConfig

string

Full nginx configuration for the service.

services:
  - hostname: app
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;
          server_name _;
          root /var/www/public;
          
          location / {
              try_files $uri $uri/ /index.php?$query_string;
          }
          
          location ~ \.php$ {
              fastcgi_pass unix:/var/run/php-fpm.sock;
              fastcgi_index index.php;
              include fastcgi_params;
          }
          
          access_log syslog:server=unix:/dev/log,facility=local1;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }

Service zerops.yaml Configuration

services[].zeropsSetup

string

Specifies which service setup to use from the zerops.yaml configuration. This should match a setup name in either the zeropsYaml parameter or the zerops.yaml file in the repository.If not specified, defaults to the service hostname.

services:
  - hostname: app
    zeropsSetup: backendapi

services[].zeropsYaml

object

Full zerops.yaml configuration embedded in the import file. If provided, this takes precedence over any zerops.yaml file in the repository.

services:
  - hostname: app
    buildFromGit: https://github.com/myorg/myapp
    zeropsSetup: backendapi
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./dist
            cache: node_modules
          run:
            start: node dist/index.js
            ports:
              - port: 3000
                httpSupport: true

How zeropsSetup and zeropsYaml Work Together

Neither parameter specified

System looks for a zerops.yaml file in the repository root
Searches for a setup with a name matching the service hostname

Only zeropsSetup specified

System looks for the specified setup name in the repository’s zerops.yaml file

Only zeropsYaml specified

System uses the provided YAML configuration
Searches for a setup with a name matching the service hostname

Both parameters specified

System uses the provided zeropsYaml configuration
Looks for the setup named in zeropsSetup within that YAML

If the specified zeropsSetup does not exist in the available YAML configuration, the import will fail.

Complete Examples

#yamlPreprocessor=on

# Define the project
project:
  name: my-production-app
  description: "Production environment"
  corePackage: SERIOUS
  tags:
    - production
    - api
  envVariables:
    LOG_LEVEL: info
    REGION: us-east-1

# Define services
services:
  # Node.js API Service
  - hostname: api
    type: nodejs@22
    mode: HA
    priority: 5
    
    envSecrets:
      SECRET_KEY: <@generateRandomString(<32>)>
      JWT_SECRET: <@generateRandomString(<64>)>
    
    objectStorageSize: 5
    objectStoragePolicy: private
    
    buildFromGit: https://github.com/myorg/api
    enableSubdomainAccess: false
    
    verticalAutoscaling:
      minCpu: 2
      maxCpu: 4
      cpuMode: DEDICATED
      minRam: 2
      maxRam: 8
      minDisk: 5
      maxDisk: 20
    
    minContainers: 2
    maxContainers: 6
    
    zeropsYaml:
      zerops:
        - setup: api
          build:
            base: nodejs@22
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./dist
            cache: node_modules
          run:
            start: node dist/index.js
            ports:
              - port: 3000
                httpSupport: true
  
  # PostgreSQL Database
  - hostname: db
    type: postgresql@16
    mode: HA
    priority: 10
    
    verticalAutoscaling:
      minCpu: 1
      maxCpu: 2
      cpuMode: SHARED
      minRam: 1
      maxRam: 4
      minDisk: 5
      maxDisk: 50
  
  # Shared Storage
  - hostname: storage
    type: shared-storage

Export Projects and Services

Zerops allows you to export existing projects and services as YAML configurations through the GUI.

Export a Single Service

Navigate to your service dashboard
Click the three-dot menu (⋮) in the top-right corner
Select Export service as yaml

Export an Entire Project

Go to the project dashboard
Click the three-dot menu (⋮) in the top-right corner
Select Export project as yaml

Using Exported Configurations

Exported YAML files are compatible with:

Zerops GUI import functionality
zcli project project-import command
zcli project service-import command

This makes it easy to:

Create backups of configurations
Replicate setups across environments
Share templates with team members
Version control your infrastructure

CLI Reference

Learn about zCLI commands for importing

zerops.yaml Specification

Full reference for build and runtime configuration

YAML Preprocessor

Generate secrets and random values

Service Types

Available service types and versions

Need help? Join our Discord community.

Get Started

Core Concepts

Configuration

​Import Methods

​File Structure

​Project Configuration

​project

​project.name

​project.description

​project.corePackage

​project.tags

​project.envVariables

​Service Configuration

​services

​Service Basic Configuration

​services[].hostname

​services[].type

​services[].mode

​services[].envSecrets

​services[].dotEnvSecrets

​services[].objectStorageSize

​services[].objectStoragePolicy

​services[].objectStorageRawPolicy

​services[].buildFromGit

​services[].enableSubdomainAccess

​services[].priority

​services[].override

​Service Vertical Autoscaling

​services[].verticalAutoscaling

​services[].verticalAutoscaling.minCpu / maxCpu

​services[].verticalAutoscaling.cpuMode

​services[].verticalAutoscaling.minRam / maxRam

​services[].verticalAutoscaling.minDisk / maxDisk

​services[].verticalAutoscaling.startCpuCoreCount

​services[].verticalAutoscaling.minFreeCpuCores

​services[].verticalAutoscaling.minFreeCpuPercent

​services[].verticalAutoscaling.minFreeRamGB

​services[].verticalAutoscaling.minFreeRamPercent

​Service Horizontal Autoscaling

​services[].minContainers

​services[].maxContainers

​Service Mount Shared Storage

​services[].mount

​Service Nginx Configuration

​services[].nginxConfig

​Service zerops.yaml Configuration

​services[].zeropsSetup

​services[].zeropsYaml

​How zeropsSetup and zeropsYaml Work Together

​Complete Examples

​Export Projects and Services

​Export a Single Service

​Export an Entire Project

​Using Exported Configurations

​Related Resources

CLI Reference

zerops.yaml Specification

YAML Preprocessor

Service Types

Build docs developers (and LLMs) love

Import Methods

File Structure

Project Configuration

project

project.name

project.description

project.corePackage

project.tags

project.envVariables

Service Configuration

services

Service Basic Configuration

services[].hostname

services[].type

services[].mode

services[].envSecrets

services[].dotEnvSecrets

services[].objectStorageSize

services[].objectStoragePolicy

services[].objectStorageRawPolicy

services[].buildFromGit

services[].enableSubdomainAccess

services[].priority

services[].override

Service Vertical Autoscaling

services[].verticalAutoscaling

services[].verticalAutoscaling.minCpu / maxCpu

services[].verticalAutoscaling.cpuMode

services[].verticalAutoscaling.minRam / maxRam

services[].verticalAutoscaling.minDisk / maxDisk

services[].verticalAutoscaling.startCpuCoreCount

services[].verticalAutoscaling.minFreeCpuCores

services[].verticalAutoscaling.minFreeCpuPercent

services[].verticalAutoscaling.minFreeRamGB

services[].verticalAutoscaling.minFreeRamPercent

Service Horizontal Autoscaling

services[].minContainers

services[].maxContainers

Service Mount Shared Storage

services[].mount

Service Nginx Configuration

services[].nginxConfig

Service zerops.yaml Configuration

services[].zeropsSetup

services[].zeropsYaml

How zeropsSetup and zeropsYaml Work Together

Complete Examples

Export Projects and Services

Export a Single Service

Export an Entire Project

Using Exported Configurations

Related Resources