Skip to main content
Skip to main content
🚧 Work in Progress

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​

FieldTypeDescription
projectobject

REQUIRED, if a whole project is imported Only one project can be defined.

namestring, REQUIRED

The name of the new project. Duplicates are allowed.

descriptionstring

Description of the new project.

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

FieldTypeDescription
serviceslist of objects, REQUIRED

At least one service is required.

hostnamestring, 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
typeenum, REQUIRED

Specifies the service type and version. See supported types.

modeenum

Values: HA / NON_HA (default NON_HA) Defines the operation mode of the service.

envSecretsmap[string]string

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

objectStorageSizeinteger

Object storage size in GB.

objectStoragePolicyenum

Values: private / public-read / public-objects-read / public-write / public-read-write / custom Select a predefined AWS S3 bucket access policy.

objectStorageRawPolicyjson

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.

buildFromGitstring (URL)

A URL of a Github or Gitlab repository used for a one-time build of your service.

enableSubdomainAccessboolean

Default: false Set true, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.

priorityinteger

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​

FieldTypeDescription
minCpuintegerMinimum number of virtual CPUs
maxCpuintegerMaximum number of virtual CPUs
cpuModeenumValues: SHARED / DEDICATED
minRamfloat

Minimum RAM in GB that each container of the service can scale down to.

maxRamfloat

Maximum RAM in GB that each container of the service can scale up to.

minDiskfloat

Minimum disk space in GB that each container of the service can scale down to.

maxDiskfloat

Maximum disk space in GB that each container of the service can scale up to.

startCpuCoreCountinteger

Number of CPU cores with which each container starts.

minFreeCpuCoresfloat

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

minFreeCpuPercentfloat

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

minFreeRamGBfloat

Minimum unused memory in GB before a container starts scaling.

minFreeRamPercentfloat

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​

FieldTypeDescription
minContainersintegerDefault: 1, maximum value: 6 - Minimum number of containers of the service.
maxContainersintegerMaximum 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​

FieldTypeDescription
mountlist of stringsMount 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​

FieldTypeDescription
nginxConfigstring (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​

FieldTypeDescription
zeropsSetupstring or objectProvide 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.