# Import & Export YAML Configuration The Import 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 Import 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](/references/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. #### Comprehensive example of an import YAML configuration 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. ```yaml # ==== 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](/features/infrastructure#project-core-options) 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](/features/env-variables#project-variables) that are available to all services in the project. | :::important The `corePackage` value can be upgraded later from Lightweight to Serious Core, but cannot be downgraded. Upgrades involve a brief service disruption and are partially destructive (logs/statistics are lost). Make sure to choose a suitable core package for your project. Learn more about [core upgrade process](/features/infrastructure#project-core-upgrade). ::: This example will create a project named `project0` with [serious core](/features/infrastructure#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`: ```yaml # ==== 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**](#service-basic-configuration) - Core parameters like hostname, type, mode, and environment variables - [**Service Vertical Autoscaling**](#service-vertical-autoscaling) - CPU, RAM, and disk scaling settings - [**Service Horizontal Autoscaling**](#service-horizontal-autoscaling) - Container count scaling settings - [**Service Mount Shared Storage**](#service-mount-shared-storage) - Connecting to shared storage services - [**Service Nginx Configuration**](#service-nginx-configuration) - Custom web server settings - [**Service zerops.yaml Configuration**](#service-zeropsyaml-configuration) - Build and run configurations #### Complete Service Configuration Example ```yaml #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](/references/import-yaml/type-list). | | 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) 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. | #### Service Basic Configuration Example ```yaml #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](/references/import-yaml/pre-processor) 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. | #### Vertical Autoscaling Configuration Example ```yaml 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 | ```yaml 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. | ```yaml 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. | ```yaml #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](/zerops-yaml/specification). If provided, this will be used instead of looking for a `zerops.yaml` file in the repository. | ```yaml 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. ## Editor support (JSON Schema) Zerops publishes an official [JSON Schema ↗](https://json-schema.org/) for the Import YAML: ``` https://api.app-prg1.zerops.io/api/rest/public/settings/import-project-yml-json-schema.json ``` With the schema attached, your editor gives you: - **Autocomplete** for every key and nested field (project, services, autoscaling, nginx, embedded `zeropsYaml`, …) - **Inline documentation** on hover - **Validation** — typos, wrong types, and missing required fields are flagged as you type - **Enum suggestions** for fields like `corePackage`, `mode`, `cpuMode`, service `type`, and more ### Auto-detection via SchemaStore The schema is registered with [SchemaStore ↗](https://www.schemastore.org/), so most YAML-aware editors apply it automatically — no setup required — when the file matches: - `zerops-import.yml`, `zerops-import.yaml` - `zerops-*-import.yml`, `zerops-*-import.yaml` (e.g., `zerops-project-import.yaml`, `zerops-service-import.yaml`) This covers VS Code (with the [YAML extension by Red Hat ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)), all JetBrains IDEs, and any editor backed by [`yaml-language-server` ↗](https://github.com/redhat-developer/yaml-language-server) (Neovim, Helix, Sublime LSP, …). ### Manual attachment If your file is named differently, add a modeline at the top: ```yaml # yaml-language-server: $schema=https://api.app-prg1.zerops.io/api/rest/public/settings/import-project-yml-json-schema.json project: name: project0 services: - hostname: app type: nodejs@22 # ... ``` The same URL works in any editor that lets you map a schema to a file pattern manually (e.g., `yaml.schemas` in VS Code `settings.json`, or JetBrains' **JSON Schema Mappings** panel).