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.
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.<name>.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.<name>.<attribute> }}, ${{ services.<name>.url }}, ${{ secrets.<name>#<field> }} or ${{ sandboxImages.<name>.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 |