Import & Export YAML Configuration

The Zerops YAML configuration provides powerful capabilities for both importing and exporting your projects and services. This documentation covers both aspects to help you effectively manage your infrastructure configurations.

Import

Create or replicate services in Zerops using YAML definitions. You can do this in two ways:

Using the GUI: Import entire projects or specific services with a simple point-and-click interface
Using the CLI: Run zcli project project-import for projects or zcli project service-import for individual services

Both methods provide an easy way to migrate or replicate your infrastructure according to your needs.

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"
# List of project tags for filtering
tags:
  - test
  - dev
# ==== Define a list of services to import into the project ====
services:
# REQUIRED. Name of your service
- hostname: service1
  # REQUIRED. Choose from list of supported technologies and their versions
  type: nodejs@latest
  # HA or NON_HA mode
  mode: HA
  # Map of secret environment variables
  envSecrets:
    SECRET_KEY: <@generateRandomString(<32>)>
    DATABASE_HOST: ${db_hostname}
    DATABASE_NAME: ${db_hostname}
  # 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/zeropsio/recipe-nodejs
  # true or false
  enableSubdomainAccess: true
  # The higher the sooner the service is created
  priority: 1
  # Vertical autoscaling configuration object
  verticalAutoscaling:
    minCpu: 1
    maxCpu: 5
    # Choose SHARED or DEDICATED
    cpuMode: DEDICATED
    minRam: 1
    maxRam: 32
    minDisk: 1
    maxDisk: 100
    startCpuCoreCount:
    minFreeCpuCores:
    minFreeCpuPercent:
    minFreeRamGB:
    minFreeRamPercent:
  # 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.yml service name or full config file
  zeropsSetup:
    build:
      base: nodejs@latest
      buildCommands:
        - echo zerops.yml from import
        - yarn
        - yarn run build
      deployFiles: ./
      cache: node_modules
    run:
      initCommands:
        - |
          if ! zcli bucket s3 create $STORAGE_HOSTNAME $STORAGE_BUCKET_NAME --x-amz-acl=private; then
          echo "The bucket was not created, you have to do it manually!"
          fi
      start: yarn start
# REQUIRED. Name of your other service
- hostname: teststorage1
  type: shared-storage
  ...

Warning

This 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.

Note

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.
tags	list of strings	One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.

# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # List of project tags for filtering
  tags:
    - test
    - dev

This will create a project with the name project0 and the description This project is an example only. The project will have two tags: test and dev.

The project object requires only the name parameter - both description and tags are optional.

Service Configuration

The service configuration is used to define the services, environment variables, and other settings you want to import into the project(You require at least one service and you need to have a project to import into or define the project in the yaml).

Usage

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

#yamlPreprocessor=on
services:
# REQUIRED: Name of your service
- hostname: service1
  # REQUIRED: Choose from list of supported technologies and their versions
  type: nodejs@latest
  # High-Availability or Non-High-Availability mode
  mode: HA
  # Map of secret environment variables
  envSecrets:
    SECRET_KEY: <@generateRandomString(<32>)>
    DATABASE_HOST: ${db_hostname}
    DATABASE_NAME: ${db_hostname}
  # 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/zeropsio/recipe-nodejs-hello-world@main
  # Enables public access via zerops.app subdomain
  enableSubdomainAccess: true
  # The higher the sooner the service is created
  priority: 1

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

Environment variables: SECRET_KEY(requires yamlPreprocessor), DATABASE_HOST and DATABASE_NAME(requires you to have a db service in the same project)
Object storage: 2GB with public-read-write policy
Git repository: https://github.com/zeropsio/recipe-nodejs-hello-world@main
Public access enabled via Zerops subdomain
Priority: 1

The services object allows you to define one or more services in the same yaml file and you can define the same parameters like hostname, type, mode, envSecrets, objectStorageSize, objectStoragePolicy, objectStorageRawPolicy, buildFromGit, enableSubdomainAccess, priority for each service no matter if it's runtime, database, etc.

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.

Vertical Autoscaling Configuration

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

Usage

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: php-nginx@8.4
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    verticalAutoscaling:
      minCpu: 1
      maxCpu: 5
      # Choose SHARED or DEDICATED
      cpuMode: DEDICATED
      minRam: 1
      maxRam: 32
      minDisk: 1
      maxDisk: 100
      startCpuCoreCount:
      minFreeCpuCores:
      minFreeCpuPercent:
      minFreeRamGB:
      minFreeRamPercent:

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-5 virtual CPUs in DEDICATED mode
RAM: 1-32 GB
Disk Space: 1-100 GB

The VerticalAutoscaling map allows you to define the vertical autoscaling settings for the service with parameters like minCpu, maxCpu, cpuMode, minRam, maxRam, minDisk, maxDisk, startCpuCoreCount, minFreeCpuCores, minFreeCpuPercent, minFreeRamGB, minFreeRamPercent.

Horizontal Autoscaling Configuration

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

Usage

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

services:
  - hostname: app
    type: php-nginx@8.4
    buildFromGit: https://github.com/example/app
    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(It automatically scales the service between the minimum and maximum number of containers) for the service.

Mount Shared Storage

The mount shared storage configuration is used to define the shared storage to mount to the service.

Usage

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

services:
  - hostname: app
    type: php-nginx@8.4
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    mount:
      - teststorage1

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

Using Nginx Configuration

The nginx configuration is used to define the nginx settings for the service.

Usage

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

#yamlPreprocessor=on
services:
  - hostname: app
    type: php-nginx@8.4
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    envSecrets:
      APP_KEY: <@generateRandomString(<32>)>
    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 use a custom nginx configuration for the service.

Using zerops.yml Configuration

This shows you how you can use the zeropsSetup parameter as a way to insert a full zerops.yml configuration file into your service using import yaml.

Usage

Field	Type	Description
zeropsSetup	string or object	Provide the name of the service from your zerops.yml (find it under `-setup: {name}`) or insert full zerops.yml configuration file.

#yamlPreprocessor=on
services:
  - hostname: app
    type: php-nginx@8.4
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    envSecrets:
      APP_KEY: <@generateRandomString(<32>)>
    zeropsSetup:
      build:
        base: php-nginx@8.4
        buildCommands:
          - composer install
        deployFiles: ./
        cache: vendor
    run:
      initCommands:
        - |
          if ! zcli bucket s3 create $STORAGE_HOSTNAME $STORAGE_BUCKET_NAME --x-amz-acl=private; then
          echo "The bucket was not created, you have to do it manually!"
          fi
      start: yarn start

The zeropsSetup: |- parameter allows you to use a custom zerops.yml configuration for the service.

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 (⋮), and choose Export service as yaml.

Exporting an Entire Project

In the Zerops GUI, click the three-dot menu (⋮) in the project dashboard and select Export project as yaml.

Using Exported Configurations

The exported YAML files are compatible with both:

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

Import​

Project Configuration​

Usage​

Service Configuration​

Usage​

Vertical Autoscaling Configuration​

Usage​

Horizontal Autoscaling Configuration​

Usage​

Mount Shared Storage​

Usage​

Using Nginx Configuration​

Usage​

Using zerops.yml Configuration​

Usage​

Export​

How to Export​

Exporting a Single Service​

Exporting an Entire Project​

Using Exported Configurations​

Import

Project Configuration

Usage

Service Configuration

Usage

Vertical Autoscaling Configuration

Usage

Horizontal Autoscaling Configuration

Usage

Mount Shared Storage

Usage

Using Nginx Configuration

Usage

Using zerops.yml Configuration

Usage

Export

How to Export

Exporting a Single Service

Exporting an Entire Project

Using Exported Configurations