Skip to content

File reference

Every key of the EZGHDeploy file, its type, whether it's required and the values it takes.

Updated View as Markdown

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
Navigation

Type to search…

↑↓ navigate↵ selectEsc close