---
title: "File reference"
description: "Every key of the EZGHDeploy file, its type, whether it's required and the values it takes."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File reference

{/* Generated by scripts/generate-deployfile-reference.ts from Deploy's JSON Schema. Don't edit: run bun run generate:deployfile. */}

Editors that read JSON Schema can check the file against `https://deploy.ezghcloud.com/schema/v1.json`. For what the keys do together, see [The EZGHDeploy file](/deploy/file).

## Top level

EZGHDeploy at the repository root. Plain YAML, strictly read: no anchors, aliases, merge keys, tags, second documents, duplicate or unknown keys, and at most 256 KiB, 8 levels of nesting and 64 items a list. Text that looks like a number or boolean (1.0, no) must be quoted.

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `version` | integer | Yes | `1` | The format version. Always 1. |
| `name` | string | Yes | matches `^[a-z][a-z0-9-]{0,39}$` | The stack's name. |
| `region` | string | Yes | `us-west-1` | The region. Always us-west-1. |
| `runtime` | object | No | – | Where services run. |
| `services` | map of objects | Yes | 1 to 50 entries; names match `^[a-z][a-z0-9-]{0,39}$` | 1 to 50 services by name. A name is a lowercase letter, then up to 39 lowercase letters, digits or -, used once across services, resources and sandbox images. |
| `resources` | map of objects | No | at most 50 entries; names match `^[a-z][a-z0-9-]{0,39}$` | Up to 50 managed resources by name. Removing one from the file detaches it; it is never deleted. |
| `sandboxImages` | map of objects | No | at most 20 entries; names match `^[a-z][a-z0-9-]{0,39}$` | Up to 20 images built like services, for the sandboxes a service with sandboxes: true starts. Each is pushed to Container Registry under ci.registry and referenced as $\{\{ sandboxImages.&lt;name&gt;.image \}\}. A name is used once across services, resources and sandbox images. |
| `secrets` | map of objects | No | names match `^[a-z][a-z0-9-]{0,39}$` | Secrets in EZGH Secrets, by name, with their fields. |
| `environments` | map of objects | Yes | 1 to 10 entries; names match `^[a-z][a-z0-9-]{0,39}$` | 1 to 10 environments by name, each a full copy of the base in its own project, with overrides. |
| `ci` | object | No | – | What a deploy waits for and where images go. |
| `alerts` | list of objects | No | at most 64 items | Obs alert rules. |

## `runtime`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `mode` | string | No | `instances` | How services run: instances, one autoscaling group per service. |
| `image` | string | No | `linux/ubuntu:24.04` | The instance image containers run on. Only linux/ubuntu:24.04 in Deploy v1. |

## `services.<name>`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `web`, `worker` | web (has a port) or worker (no port). |
| `source` | string | No | – | A directory in the repository whose language and framework are detected; no Dockerfile needed. One of source, dockerfile, image or from. |
| `dockerfile` | string | No | – | A directory in the repository holding your Dockerfile (./services/api/ builds services/api/Dockerfile), or a Dockerfile's own path, such as ./services/api/Dockerfile.prod. The build context is the repository root. |
| `image` | string | No | – | A prebuilt image: a repository path with an optional :tag or @sha256 digest. |
| `from` | string | No | matches `^[a-z][a-z0-9-]{0,39}$` | Another service whose image this one runs, usually with a different command. That service can't itself use from. |
| `build` | object | No | – | Overrides what detection found. Only with source. |
| `command` | string | No | – | The command the container runs instead of the image's own. |
| `port` | integer | No | 1 to 65535 | The port a web service listens on. Required for web, refused otherwise. |
| `public` | object | No | – | Makes a web service public: domains, a load balancer, and optionally the CDN and WAF. Without it a service is private. |
| `health` | object | No | – | The load balancer's health check. web only. |
| `instanceType` | string | No | – | The instance type, in instances mode. |
| `scale` | object | No | – | How many instances, and the target they scale on. |
| `rollout` | object | No | – | How a new version replaces the old one. Default rolling. |
| `release` | object | No | – | A command run once per deploy, before the rollout; failure stops the deploy. |
| `shutdown` | object | No | – | Time a stopping instance gets to finish its work. |
| `sandboxes` | boolean | No | – | Whether the service's Bot may create and use EZGH Sandboxes in the environment's project. Needed to reference a sandbox image. |
| `access` | map of strings | No | names match `^[a-z][a-z0-9-]{0,39}$`; values: `readOnly`, `readWrite`, `owner` | Database access by resource key: readOnly, readWrite or owner. Each key is a database the service references in env; a referenced database left out is readWrite. |
| `env` | map of strings | No | names match `^[A-Za-z_][A-Za-z0-9_]{0,127}$` | Environment variables: text, or exactly one reference as the whole value: $\{\{ resources.&lt;name&gt;.&lt;attribute&gt; \}\}, $\{\{ services.&lt;name&gt;.url \}\}, $\{\{ secrets.&lt;name&gt;#&lt;field&gt; \}\} or $\{\{ sandboxImages.&lt;name&gt;.image \}\}. References are allowed only here. |

## `services.<name>.build`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `installCommand` | string | No | – | Replaces the detected install command. |
| `buildCommand` | string | No | – | Replaces the detected build command. |
| `startCommand` | string | No | – | Replaces the detected start command. |

## `services.<name>.public`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `domains` | list of strings | No | at most 64 items; each item once | Hostnames served, with certificates issued and renewed by Certificates. With the CDN, not an apex domain such as example.com. Without domains there's no certificate: the service is reached over http at its load balancer's address, or at the CDN's default hostname when cdn is enabled. |
| `lb` | object | No | – | The load balancer's listener. |
| `cdn` | object | No | – | A CDN distribution in front of the load balancer. |
| `waf` | object | No | – | A WAF on the load balancer. |

## `services.<name>.public.lb`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `protocol` | string | No | – | The listener's protocol: https, http, tls or tcp. Default https with domains, http without; https and tls need at least one domain. |
| `idleTimeoutSeconds` | integer | No | – | The listener's idle timeout, in seconds. |

## `services.<name>.public.cdn`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `enabled` | boolean | No | – | Whether the distribution is on. Caching follows your Cache-Control headers. |
| `rewrites` | list of objects | No | at most 64 items | Path rewrites at the edge, in order. |

## `services.<name>.public.cdn.rewrites[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `pattern` | string | Yes | – | The path pattern to match. |
| `replacement` | string | Yes | – | The path it is rewritten to. |

## `services.<name>.public.waf`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `enabled` | boolean | No | – | Whether the WAF is on. |
| `mode` | string | No | – | block or log. |
| `managedRuleSets` | list of strings | No | at most 64 items; each item once | Managed rule sets by name, such as ezgh/core. |

## `services.<name>.health`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `path` | string | No | – | The HTTP path checked. |
| `intervalSeconds` | integer | No | – | Seconds between checks. |
| `timeoutSeconds` | integer | No | – | Seconds a check may take. |
| `healthyThreshold` | integer | No | – | Passing checks before a target is healthy. |
| `unhealthyThreshold` | integer | No | – | Failing checks before a target is unhealthy. |

## `services.<name>.scale`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `min` | integer | No | at least 0 | The fewest instances. |
| `max` | integer | No | at least 1 | The most instances; at least min. |
| `target` | object | No | – | What scaling keeps steady. |

## `services.<name>.scale.target`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `cpuUtilization` | integer | No | 1 to 100 | Target CPU, in percent. Exactly one of cpuUtilization or memoryUtilization. |
| `memoryUtilization` | integer | No | 1 to 100 | Target memory, in percent. |

## `services.<name>.rollout`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `strategy` | string | No | `rolling`, `canary` | rolling (the default) or canary. canary needs public. |
| `batchPercent` | integer | No | 1 to 100 | rolling: the share of instances replaced at a time. |
| `steps` | list of objects | No | 1 to 64 items | canary: traffic weights that rise from 1 to 100, ending at 100. |

## `services.<name>.rollout.steps[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `weight` | integer | Yes | 1 to 100 | The new version's share of traffic, in percent. |
| `pause` | string | No | matches `^[1-9][0-9]{0,5}(s\|m\|h)$` | How long to wait before the next step, such as 5m. |

## `services.<name>.release`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `command` | string | Yes | – | The command run once per deploy, before the rollout. |
| `timeout` | string | No | matches `^[1-9][0-9]{0,5}(s\|m\|h)$` | How long it may run, such as 10m. |

## `services.<name>.shutdown`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `graceSeconds` | integer | Yes | at least 0 | Seconds a stopping instance gets to finish its current work. |

## `resources.<name>` (database)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `mysql`, `percona`, `mariadb`, `postgresql` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `engineVersion` | string | No | – | The engine version, such as "8.4" or "18"; quote it. |
| `instanceType` | string | No | – | The instance type of each of the pair's nodes. |
| `storage` | object | No | – | Storage per node. |
| `backup` | object | No | – | Backup retention. |
| `deletionProtection` | boolean | No | – | Whether the database refuses deletion. |
| `parameters` | map of strings | No | – | Engine parameters, by name, as text. |
| `logicalDatabases` | list of strings | No | at most 64 items; each item once; items match `^[a-z_][a-z0-9_]{0,62}$` | Logical databases created in it. A reference to the database reaches the first one. Removing one detaches it and never drops it. |

## `resources.<name>.storage`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `sizeGiB` | integer | Yes | at least 1 | Size in GiB. |

## `resources.<name>.backup`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `retentionDays` | integer | Yes | at least 1 | Days backups are kept. |

## `resources.<name>` (cache)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `redis`, `valkey`, `memcached` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `engineVersion` | string | No | – | The engine version, such as "9.1"; quote it. |
| `instanceType` | string | No | – | The instance type. |
| `mode` | string | No | – | memory, or persistent (valkey only, needs storage). |
| `standby` | boolean | No | – | Whether a standby node runs beside the primary. |
| `storage` | object | No | – | Storage, for persistent mode. |
| `parameters` | map of strings | No | – | Engine parameters, by name, as text. |

## `resources.<name>` (queue)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `queue` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `queueType` | string | No | – | standard or fifo; fixed at creation. |
| `visibilityTimeoutSeconds` | integer | No | – | Seconds a received message stays hidden. |
| `retentionSeconds` | integer | No | – | Seconds a message is kept. |
| `redrive` | object | No | – | Where messages go after too many receives. |

## `resources.<name>.redrive`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `deadLetterQueue` | string | Yes | matches `^[a-z][a-z0-9-]{0,39}$` | Another queue in this file, by key, with the same queueType. |
| `maxReceiveCount` | integer | Yes | – | Receives before a message moves to the dead-letter queue. |

## `resources.<name>` (bucket)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `bucket` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `publicRead` | boolean | No | – | Whether anyone can read its objects. |
| `corsRules` | list of objects | No | at most 64 items | CORS rules. |

## `resources.<name>.corsRules[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `allowedOrigins` | list of strings | No | at most 64 items; each item once | Origins allowed. |
| `allowedMethods` | list of strings | No | at most 64 items; each item once | Methods allowed. |
| `allowedHeaders` | list of strings | No | at most 64 items; each item once | Request headers allowed. |
| `exposeHeaders` | list of strings | No | at most 64 items; each item once | Response headers exposed. |
| `maxAgeSeconds` | integer | No | – | Seconds a preflight answer may be cached. |

## `resources.<name>` (kafka)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `kafka` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `engineVersion` | string | No | – | The engine version, such as "4.4"; quote it. 4.4 when left out. |
| `instanceType` | string | No | – | Every node's instance type. gs-1.large when left out. |
| `mode` | string | No | `single`, `replicated` | single (one node), or replicated (three, on three hosts); single when left out. A cluster grows to replicated and never back. |
| `storage` | object | No | – | Storage per node; 20 GiB when left out. It never shrinks. |
| `access` | string | No | `admin`, `readWrite`, `readOnly` | The preset of each referencing service's own user: admin, readWrite or readOnly; readWrite when left out. |
| `topics` | list of objects | No | at most 64 items | Topics Deploy creates. Removing one leaves it in place; Deploy never deletes a topic. |

## `resources.<name>.topics[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$` | The topic's name. |
| `partitions` | integer | No | 1 to 1000 | Partitions, 1 to 1000; only ever more. |
| `replicationFactor` | integer | No | 1 to 3 | Copies of each partition, 1 to 3 (above 1 needs mode: replicated); only ever more. |

## `resources.<name>` (rabbitmq)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `rabbitmq` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `engineVersion` | string | No | – | The engine version, such as "4.4"; quote it. 4.4 when left out. |
| `instanceType` | string | No | – | Every node's instance type. gs-1.large when left out. |
| `mode` | string | No | `single`, `replicated` | single (one node), or replicated (three, on three hosts); single when left out. A cluster grows to replicated and never back. |
| `storage` | object | No | – | Storage per node; 20 GiB when left out. It never shrinks. |
| `vhost` | string | No | matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$` | The vhost the queues are in, and that each referencing service's own user may read and write; the default vhost when left out. Never deleted. |
| `queues` | list of objects | No | at most 64 items | Queues Deploy creates in the vhost. Removing one leaves it in place; Deploy never deletes a queue. |

## `resources.<name>.queues[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$` | The queue's name. |
| `type` | string | No | `quorum`, `classic`, `stream` | quorum, classic or stream; the vhost's default (quorum) when left out. Fixed at creation. |

## `resources.<name>` (warehouse)

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | `warehouse` | The resource's type. |
| `name` | string | No | – | The product resource's name. Defaults to the resource's key. |
| `engineVersion` | string | No | – | The ClickHouse version, such as "26.8"; quote it. 26.8 when left out. It only moves to a newer version. |
| `instanceType` | string | No | – | Every node's instance type, with at least 8 GiB of memory. gp-1.large when left out. |
| `shards` | integer | No | 1 to 8 | Shards, 1 to 8; 1 when left out. Existing data stays on the current shards; rows inserted through a Distributed table spread across all shards by its sharding key. |
| `replicas` | integer | No | 1 to 3 | Replicas of each shard, 1 to 3; 1 when left out. Each shard keeps serving through the loss of one node with 2 or 3 replicas. |
| `storage` | object | No | – | Storage per node; 100 GiB when left out. It never shrinks. |
| `access` | string | No | `admin`, `readWrite`, `readOnly` | The preset of each referencing service's own user: admin, readWrite or readOnly; readWrite when left out. |
| `databases` | list of objects | No | at most 64 items | Databases Deploy creates. Removing one leaves it in place; Deploy never deletes a database. A database that already exists is kept. |

## `resources.<name>.databases[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | matches `^[A-Za-z_][A-Za-z0-9_]{0,63}$` | The database's exact name. |

## `sandboxImages.<name>`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `source` | string | No | – | A directory in the repository whose language and framework are detected; no Dockerfile needed. One of source or dockerfile. |
| `dockerfile` | string | No | – | A directory in the repository holding your Dockerfile, or a Dockerfile's own path, such as ./sandbox/python.Dockerfile. The build context is the repository root. |
| `build` | object, as `services.<name>.build` | No | – | Overrides what detection found. Only with source, and without startCommand: a sandbox has no start command. |

## `secrets.<name>`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `fields` | list of strings | Yes | at most 64 items; each item once; items match `^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$` | The secret's fields. Values never go in this file. |
| `generate` | map of objects | No | – | Fields created on the first deploy if absent, with their length. |

## `secrets.<name>.generate.<name>`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `length` | integer | Yes | 16 to 4096 | The generated value's length. |

## `environments.<name>`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `branch` | string | Yes | – | The branch this environment deploys from. It must match the branch the environment is registered for. |
| `project` | string | Yes | – | The project this environment deploys into: its prj_ ID or its name. It must match the registered project. |
| `approve` | boolean | No | – | Whether a person approves each plan before it applies. |
| `overrides` | object | No | – | Changes to the base for this environment: a deep merge, where a list replaces the whole list. |

## `environments.<name>.overrides`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `services` | map of objects, as `services.<name>` | No | – | Changes to services the base has, by key. |
| `resources` | map of objects, as `resources.<name>` | No | – | Changes to resources the base has, by key. |
| `sandboxImages` | map of objects, as `sandboxImages.<name>` | No | – | Changes to sandbox images the base has, by key. |
| `runtime` | object, as `runtime` | No | – | Changes to runtime. |

## `ci`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `requires` | list of strings | No | at most 64 items; each item once; items match `^[a-z][a-z0-9-]{0,39}$` | EZGH Build tasks that must pass before a deploy. |
| `registry` | string | No | matches `^[a-z0-9]+(?:[._-][a-z0-9]+)*$` | The Container Registry scope built images are pushed to. Required when a service uses source or dockerfile, or the file has sandbox images. |

## `alerts[]`

| Key | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | – | The alert rule's name, unique in the file. |
| `promql` | string | Yes | – | The PromQL condition. |
| `for` | string | No | matches `^[1-9][0-9]{0,5}(s\|m\|h)$` | How long the condition holds before the alert fires, such as 5m. |
| `contactPoints` | list of strings | No | at most 64 items; each item once | Existing Obs contact points, by name. |

## References

An `env` value can be exactly one reference: `${{ resources.<name>.<attribute> }}`, `${{ services.<name>.url }}` or `${{ secrets.<name>#<field> }}`. The attributes of each type:

| Type | Attributes |
| --- | --- |
| `percona` | `uri`, `host`, `port`, `user`, `database` |
| `mariadb` | `uri`, `host`, `port`, `user`, `database` |
| `postgresql` | `uri`, `host`, `port`, `user`, `database` |
| `valkey` | `uri`, `host`, `port`, `user`, `database` |
| `memcached` | `uri`, `host`, `port`, `user` |
| `queue` | `id`, `name` |
| `bucket` | `name`, `endpoint` |
| `service` | `url` |
| `kafka` | `bootstrapServers`, `host`, `port`, `username`, `password`, `saslMechanism`, `securityProtocol`, `id`, `name` |
| `rabbitmq` | `uri`, `host`, `port`, `vhost`, `username`, `password`, `id`, `name` |
| `warehouse` | `url`, `host`, `httpsPort`, `nativePort`, `username`, `password`, `database`, `id`, `name` |
| `sandboxImage` | `image` |

Source: https://docs.ezghcloud.com/deploy/file-reference/index.mdx
