Application manifest reference
An application is described by one Pkl module, usually named orch.pkl, that
amends the versioned v1/Application.pkl schema. The schema is
embedded in the orch binary, so orch never downloads it; editors fetch the
same file from GitHub for completion and type checks. This page lists every field it defines, with
its type, default, and the rules that orch validate enforces on top of the
Pkl types.
For a guided introduction, start with applications. For the commands that read this file, see the CLI reference.
amends "https://orch.torsten.work/pkl/v1/Application.pkl"
name = "shop"
services {
["web"] {
image = "ghcr.io/acme/shop:2.3.0"
replicas = 2
http = new Http {
port = 8080
domains { "shop.example.com" }
healthPath = "/healthz"
}
}
}How a manifest is evaluated
orch validate, orch render, orch plan, and orch deploy all follow the
same steps on your workstation:
- Pkl evaluates the module and applies the schema's types and defaults.
- orch converts the result to its resolved model and runs its own validation. Some rules, such as "a domain may only be routed by one service", cannot be expressed in Pkl types and are only checked here.
- orch normalizes the result and produces canonical JSON and a
sha256:digest.
Only the canonical JSON is sent to the controller. Controllers and workers never run Pkl. The controller decodes the JSON again, rejects unknown fields or JSON that is not in canonical form, and repeats the validation.
Evaluation needs the pkl executable on your PATH, at exactly the version
pinned by orch (currently 0.32.1). The repository installs it with
mise install. Evaluation is limited to 10 seconds, and both the source file
and the resolved JSON are limited to 1 MiB.
Unknown fields
The schema is closed. Assigning a property that does not exist is an evaluation error, and Pkl suggests the closest name:
$ orch validate
evaluate Pkl manifest "orch.pkl": –– Pkl Error ––
Cannot find property `replica` in object of type `orch.Application#Service`.
...
Did you mean any of the following?
replicasAuthoring commands exit with status 2 for evaluation and validation errors.
Validation errors
When the Pkl types pass but orch's own rules do not, every problem is listed with its path in the resolved model. Paths use the snake_case names of the canonical JSON, not the camelCase names you write in Pkl:
$ orch validate
manifest is invalid
cron_jobs.cleanup.schedule: cron schedule must use five UTC fields without timezone directives or descriptors
deploy: max_surge and max_unavailable cannot both be zero
services.web: http and tcp endpoints cannot both be configured
services.web.http.health_path: is required when public HTTP ingress or domains are configuredPass --json to orch validate for machine-readable output.
Defaults and normalization
Every field with a default is filled in before validation, so the resolved
manifest is always complete. orch render prints it:
$ orch render
{
"schema": "v1",
"name": "shop",
"services": {
"web": {
"image": "ghcr.io/acme/shop:2.3.0",
"replicas": 2,
"restart": "always",
"resources": {
"cpu": "100m",
"memory": "128Mi"
},
...orch then normalizes values that have more than one spelling, so equivalent sources produce the same digest:
- A whole CPU count becomes millicores:
cpu = "2"renders as"2000m". - Domains,
dependsOn, secret files (by target) and mounts (by target) are sorted. - Empty lists and maps are omitted from the canonical JSON.
Because the digest covers the resolved result, refactoring a manifest into shared modules, or reordering entries, does not change it.
Plan
orch plan compares two local manifests. Without --against, everything is
shown as an addition. With --against, it lists the resolved fields that
differ:
$ orch plan -f orch.pkl --against orch.previous.pkl
Plan for shop (sha256:60eeea1b...)
~ services.web.replicas: 2 -> 3
~ services.web.resources.cpu: "100m" -> "2000m"
Plan: 0 to add, 2 to change, 0 to remove.Both files must describe the same application name. Defaults that you did
not write still appear in the plan, because the comparison uses the resolved
model. orch plan does not contact the cluster. To compare stored revisions on
the cluster, use orch app diff; see deployments.
Top level
| Field | Type | Default | Rules |
|---|---|---|---|
schema |
"v1" |
"v1" |
Set by the schema you amend; "v1alpha1" for manifests that amend the pre-1.0 URL. You do not set it. |
name |
DNS label | required | Application name, unique in the cluster |
services |
Mapping<DnsLabel, Service> |
empty | At most 100; an application needs a service or a database |
cronJobs |
Mapping<DnsLabel, CronJob> |
empty | At most 100 |
volumes |
Mapping<DnsLabel, Volume> |
empty | At most 100 |
notifications |
Listing<Notification> |
empty | At most 20; see Notification |
databases |
Mapping<DnsLabel, Database> |
empty | At most 20; see Databases |
deploy |
Deployment |
defaults below | Rollout behavior and pre-deploy hook |
allowPrivateNetwork |
Boolean |
false |
Let workloads reach hosts on private networks such as the node's VPC; administrator credentials only. See what workloads can reach |
Across all services an application may request at most 200 replicas in total and route at most 1000 domains in total.
Shared types
| Type | Accepted values |
|---|---|
| DNS label | 1 to 63 characters: lowercase letters, digits and -; starts with a letter and does not end with - |
| Environment name | Starts with a letter or _, then letters, digits or _ |
| Manifest string | At most 4096 bytes and no NUL bytes |
| Port | Integer from 1 to 65535 |
| Duration | A Go duration string such as "30s", "5m" or "1h30m". Each duration field has its own range. |
Application, service, cron job, volume and secret names all use the DNS label
rule. A service named api in application shop is reachable at
api.shop.svc.internal; see service discovery.
Service
A long-running workload. Each entry under services is a Service.
| Field | Type | Default | Rules |
|---|---|---|---|
image |
String | required | Valid OCI reference, at most 1024 bytes. Not with static. |
static |
Static? |
null |
Serve a folder instead of an image; see static sites |
command |
Listing<String> |
image default | At most 256 entries, each nonblank |
args |
Listing<String> |
image default | At most 256 entries, each nonblank |
replicas |
Int | 1 |
1 to 100; must be 1 when the service mounts a volume |
restart |
String | "always" |
"always", "on-failure" or "never" |
resources |
Resources |
100m, 128Mi |
See resources |
http |
Http | Listing<Http> |
null |
See Http. Not together with tcp. |
tcp |
Tcp? |
null |
See Tcp. Not together with http. |
udp |
Udp? |
null |
See Udp. Requires http or tcp. |
dependsOn |
Listing<DnsLabel> |
empty | At most 64 distinct services of this application |
env |
Mapping<EnvironmentName, String> |
empty | At most 256 entries |
secretEnv |
Mapping<EnvironmentName, DnsLabel> |
empty | At most 256 entries; secret names |
connect |
Mapping<EnvironmentName, DatabaseName> |
empty | At most 20; see Databases |
secretFiles |
Listing<SecretFile> |
empty | At most 64 |
constraints |
Mapping<String, String> |
empty | At most 64 required node labels |
mounts |
Listing<Mount> |
empty | At most 64 |
stopGracePeriod |
String? |
null (10s) |
Whole seconds from "1s" to "10m" |
privileged |
Boolean | false |
See privileged services |
capabilities |
Listing<String> |
empty | Up to 41 distinct canonical Linux CAP_* names; administrator-only; not with privileged |
autoscale |
Autoscale? |
null |
See autoscaling. Leave replicas unset. |
Image
Tags are resolved to immutable digests by the controller when a deployment is accepted, so every replica of a revision runs the same image. A rollback reuses the recorded digests. Images from private registries need a registry credential; see secrets and registry credentials.
Static sites
A service with static serves a folder of files, such as a site generator's
build output, without a Dockerfile or a container engine. orch deploy packs
the folder into an image with a web server, uploads it to the controller, and
deploys it like any other service, with its replicas, domains, HTTPS and
rollbacks.
| Field | Type | Default | Rules |
|---|---|---|---|
dir |
String | required | Folder to serve, relative to the manifest. It must be inside the evaluation root (the manifest's folder unless --root is given) |
spa |
Boolean | false |
Answer unknown paths with /index.html, for client-side routing |
services {
["web"] {
static = new Static { dir = "dist" }
http { domains { "example.com" } }
}
}A static service gets an http endpoint on port 8080 with a health check, so
http { ... } only adds domains or other settings to it. A different
healthPath must be a file in the folder, such as / for its index.html. It
can't also set image, command or args.
Build the site before deploying; orch deploy serves whatever is in the
folder. Files and folders whose names start with a dot, such as .env or
.git, are left out, except .well-known. Links to files inside the folder
are followed; links to folders, hidden files, or anything outside it stop the
deploy. Without spa, unknown paths get
the folder's 404.html with status 404, if it has one. Responses are
compressed, and an unchanged folder is not uploaded again.
The web server is the Caddy release that ingress nodes run, without a shell or anything else, running as an unprivileged user. orch downloads it once into your user cache directory and checks its pinned checksum.
Stopping
When a replica is replaced, removed, or drained, orch sends it SIGTERM and
waits stopGracePeriod before it sends SIGKILL. The default is 10 seconds.
Give servers that save state on shutdown, such as game servers, more time:
services {
["game"] {
image = "ghcr.io/acme/game:1.4"
stopGracePeriod = "2m"
}
}Changing it replaces the replica, like any other change to the service.
Privileged services
Replicas default to no Linux capabilities, no new privileges, the
default seccomp profile, and no access to the node's devices. A service that
must start containers of its own, such as a Docker daemon that runs build or
function sandboxes, can set privileged = true to lift all of that:
services {
["docker"] {
image = "docker.io/library/docker:29-dind"
privileged = true
mounts {
new Mount { source = "docker"; target = "/var/lib/docker" }
}
}
}A privileged replica can take over the node it runs on, so only administrator credentials may deploy an application that has one. Deploys with a deployer certificate, an access token, or from GitHub are refused. Give the service a local volume for its working state: a Docker daemon cannot run its overlay storage on the container's own root filesystem.
Linux capabilities
When an image needs specific startup permissions, prefer an explicit
capabilities list to privileged mode. For example, an init process that fixes
volume ownership, switches UID/GID and later signals the child process can use:
services {
["media"] {
image = "ghcr.io/acme/media:1.4"
capabilities {
"CAP_CHOWN"
"CAP_KILL"
"CAP_SETGID"
"CAP_SETUID"
}
}
}Only the listed capabilities are placed in the OCI bounding, permitted and
effective sets. No ambient or inheritable capabilities are added. The default
seccomp profile, no-new-privileges, blocked host devices and other confinement
remain in effect. An image may drop these permissions itself after startup.
Use exact Linux names including CAP_; unknown names, duplicates and ALL are
rejected. The list is sorted in canonical JSON, omitted when empty, and changing
it replaces the replica. It cannot be combined with privileged = true.
Some capabilities, such as CAP_SYS_ADMIN, can substantially weaken isolation
despite the remaining confinement. Deploying or rolling back to an application
with any capability grants requires administrator credentials, including when
the application otherwise permits scoped deployer tokens or GitHub deployment.
Upgrade the CLI, controller and all workers to a release supporting capabilities
before deploying a manifest that uses them.
Autoscaling
With autoscale, the controller adds and removes replicas to keep the
service's average CPU use near a share of its CPU request:
services {
["web"] {
image = "ghcr.io/acme/web:1.4"
resources { cpu = "500m"; memory = "256Mi" }
autoscale = new Autoscale {
min = 2
max = 10
}
}
}| Field | Type | Default | Rules |
|---|---|---|---|
min |
Int | 1 |
1 to 100; the replica count of a first deploy |
max |
Int | required | min to 100; counts toward the 200-replica limit |
cpuPercent |
Int | 70 |
10 to 100; target average CPU use as a percent of resources.cpu |
Every 30 seconds the controller averages the last minute of CPU use of the service's ready replicas, as reported by their nodes. When it is more than 10% away from the target, the replica count changes in proportion, at most doubling at once. It adds replicas right away and removes them one at a time, only after every evaluation in the last five minutes asked for fewer. It waits while a deployment of the application is rolling out.
Scaling is not a deployment: it keeps the current revision, adds nothing to
history, and orch plan shows no change. A new deployment keeps the current
count within the new min and max. Each change is a service.scaled
event that says why, and orch app status shows the count, CPU use and target.
When no node has room for another replica, the service stays at the count that
fits and orch app status says it is limited. Add a node or lower the request.
autoscale is not available for services that mount a volume or publish
node-local ports. Since CPU requests are also CPU limits, a replica can never
use more than 100% of its request, so leave headroom below 100.
Command and args
command and args follow the usual container rules:
commandset: the process iscommandfollowed byargs. The image's entry point and default arguments are ignored.- Only
argsset: the image's entry point runs withargsin place of the image's default arguments. - Neither set: the image's configuration is used as is.
services {
["worker"] {
image = "ghcr.io/acme/shop:2.3.0"
command { "/app/bin/worker" }
args { "--queue" "default" }
}
}Restart
| Value | Behavior |
|---|---|
"always" |
Restart the process whenever it exits |
"on-failure" |
Restart only after a nonzero exit |
"never" |
Do not restart |
Dependencies
dependsOn names other services in the same application. A dependency counts
as available when at least one of its replicas is running, or ready if it has
an endpoint. The gate applies before starts, restarts, replacements and
rollbacks. A later outage of the dependency does not stop a dependent that is
already running.
orch rejects dependencies that are unknown, duplicated, on the service itself, or that form a cycle.
Environment and secrets
env holds plain values. secretEnv maps an environment variable to the name
of a stored secret. connect maps an environment variable to one of the
application's databases and sets it to that database's
connection URL. A variable can appear in only one of the three.
env {
["APP_ENV"] = "production"
["LOG_LEVEL"] = "info"
}
secretEnv {
["DATABASE_URL"] = "database-url"
}
secretFiles {
new SecretFile {
source = "tls-key"
target = "/run/secrets/tls.key"
}
}SecretFile has two fields:
| Field | Type | Rules |
|---|---|---|
source |
DNS label | Name of a stored secret |
target |
String | Clean absolute path below /run/secrets/, unique per workload |
How secrets are stored, delivered and rotated is described in secrets and registry credentials.
Constraints
Each entry is an exact node-label match that every replica requires:
constraints {
["region"] = "eu-west"
}Keys and values must be nonblank; keys are at most 256 bytes. Besides the
labels you set with orch node label, every node also has orch.node (its
name), orch.os and orch.arch. If no node matches, the service stays
blocked. See placement.
Mounts
A Mount attaches a declared volume:
| Field | Type | Default | Rules |
|---|---|---|---|
source |
DNS label | required | Must name an entry in volumes |
target |
String | required | Clean absolute path, unique per workload |
readOnly |
Boolean | false |
Must be true in cron jobs |
The target cannot be / or lie in /proc, /sys, /dev, /run/orch, or
be /etc/resolv.conf. A volume can be mounted by only one service, and that
service must have replicas = 1.
Resources
| Field | Type | Default | Rules |
|---|---|---|---|
cpu |
String | "100m" |
A positive whole count such as "2", or millicores such as "250m" |
memory |
String | "128Mi" |
A positive integer with Ki, Mi, Gi or Ti |
The scheduler reserves these amounts on the node, and memory is enforced as a
hard limit without swap. Decimal values such as "0.5" or units such as
"512M" are rejected.
Http
An HTTP endpoint. Ingress nodes route the listed domains to ready replicas.
| Field | Type | Default | Rules |
|---|---|---|---|
port |
Port | required | Port the container listens on |
public |
Boolean | false |
Catch-all plaintext listener on ingress port 80 |
domains |
Listing<String> |
empty | At most 100 distinct hostnames |
healthPath |
String | "" |
Required when public or domains is set |
https |
Boolean | true |
Obtain certificates and redirect HTTP to HTTPS |
basicAuth |
BasicAuth? |
null |
Ask for a username and password first |
redirects |
Mapping<String, String> |
empty | Domains that redirect to one of domains |
paths |
Listing<String> |
empty | Serve only these path prefixes of domains, such as "/api" |
stripPrefix |
Boolean | false |
Remove the matched prefix before forwarding |
Rules for domains:
- Lowercase, fully qualified hostnames with at least one dot. No trailing
dots, IP addresses,
localhost, or names undersvc.internal. - A domain may start with
*.to match any one label, such as*.example.comforshop.example.com. Exact domains win over wildcards. See wildcard domains. - Internationalized names must be written in their ASCII (
xn--) form. - A domain may be routed by only one service, unless the services split it
by path. Across applications, the application created first
keeps the domain (or the path); a later one is blocked with
domain_conflict.
Rules for healthPath: it must start with /, be at most 2048 bytes, and
contain no newline or NUL bytes. Without it, readiness uses a TCP connection
check, which is only allowed for services with no domains and no public
listener.
With https = true, a domain receives a certificate automatically and plain
HTTP requests are redirected with 308. With https = false, the domain is
served over plain HTTP on port 80. The public catch-all listener is always
plain HTTP, and only one service in the cluster can own it.
http = new Http {
port = 8080
domains {
"shop.example.com"
"www.shop.example.com"
}
healthPath = "/healthz"
}See networking for DNS and firewall requirements.
Basic auth
basicAuth puts a username and password in front of every domain of the
service. Ingress answers 401 until the browser sends the right account, so
the service never sees an unauthenticated request. It needs domains served
over HTTPS and no public listener, so the password is never sent in the
clear.
| Field | Type | Rules |
|---|---|---|
user |
String | 1–64 letters, digits, ., _ or - |
passwordSecret |
DnsLabel | Name of the application secret that holds the password |
http = new Http {
port = 8080
domains { "admin.example.com" }
healthPath = "/healthz"
basicAuth = new BasicAuth { user = "admin"; passwordSecret = "admin-password" }
}printf '%s' "$ADMIN_PASSWORD" | orch secret set APP admin-password --from-stdinThe controller hashes the password with argon2id and only the hash reaches the
nodes. The hash is kept cheap so that requests with random passwords cannot
wear down a node's ingress, so use a long random password, for example from
openssl rand -base64 24, rather than a word someone could guess. Setting a
new value for the secret rolls the service like any other secret change.
Health checks go straight to the replica, so they don't need the password. orch dev leaves basic auth off.
Redirects
redirects sends every request for a domain to one of the service's
domains with a permanent 308, keeping the path and query. A redirected
domain gets its own certificate when https = true, follows the same rules as
domains, and can't also be in domains.
http = new Http {
port = 8080
domains { "example.com" }
healthPath = "/healthz"
redirects { ["www.example.com"] = "example.com" }
}Paths
paths lets several services share a domain, such as a frontend on / and
an API on /api. A service with paths answers only requests under those
prefixes on its domains; a service without paths answers everything
else. When prefixes overlap, the longest one wins, so /api/admin can go to
a third service.
services {
["web"] {
image = "ghcr.io/acme/web:1.0.0"
http = new Http {
port = 3000
domains { "example.com" }
healthPath = "/"
}
}
["api"] {
image = "ghcr.io/acme/api:1.0.0"
http = new Http {
port = 8080
domains { "example.com" }
paths { "/api" }
stripPrefix = true
healthPath = "/healthz"
}
}
}A prefix matches itself and everything below it: /api serves /api and
/api/users, but not /apikeys. With stripPrefix = true the service sees
/api/users as /users; without it, the full path is forwarded. Paths
start with /, use lowercase letters, digits, ., _, ~ or -, have no
trailing slash, and a service has at most 20. Path routes work across
applications too, so a frontend and a backend deployed from different
repositories can share a domain.
Services sharing a domain must agree on https. The domain gets one
certificate. paths can't be combined with public, and healthPath is
unaffected, because health checks go straight to the replica. Under
orch dev, a service with paths shares the local domain of the service
that serves the rest of the domain, so relative links such as /api keep
working.
Several ports
A container that serves HTTP on more than one port, such as an API and a web
console, takes a listing of Http entries, each with its own port and
domains:
http = new Listing {
new Http {
port = 9000
domains { "s3.example.com" }
healthPath = "/health"
}
new Http {
port = 9001
domains { "console.example.com" }
}
}The entries are one endpoint of the service. Readiness checks the first
entry, so only it takes healthPath and public. Every entry needs its own
port and at least one domain, may have its own redirects, and uses the same
https, nodeLocal, basicAuth, paths and stripPrefix as the first. A single Http, as above,
is the same as a listing with one entry. Under orch dev, each later entry is
served on SERVICE-PORT.APP.localhost.
Tcp
A raw TCP endpoint.
| Field | Type | Default | Rules |
|---|---|---|---|
port |
Port | required | Port the container listens on |
publicPort |
Port? |
null |
Opened on every ingress node and proxied to ready replicas |
nodePort |
Port? |
null |
Published on the node that runs each replica |
publicPort cannot be 22, 53, 80, 443 or 9443, and two services cannot use
the same one. nodePort cannot be 22, 53, 80, 443 or 9443, and cannot reuse a
publicPort of another service in the application.
tcp = new Tcp {
port = 5432
publicPort = 15432
}Udp
A UDP endpoint published on the node that runs each replica.
| Field | Type | Default | Rules |
|---|---|---|---|
port |
Port | required | Port the container listens on |
nodePort |
Port | required | Cannot be 53 or 51820 |
UDP is not health checked, so a service with udp must also have http or
tcp; its replica is published once that endpoint is ready.
Any service that sets tcp.nodePort or udp makes the whole application use
deploy.maxSurge = 0. Read node-local TCP and UDP
before using them.
services {
["game"] {
image = "ghcr.io/example/game:1.4.2"
tcp = new Tcp {
port = 7777
nodePort = 7777
}
udp = new Udp {
port = 7777
nodePort = 7777
}
}
}
deploy {
maxSurge = 0
maxUnavailable = 1
}Volume
| Field | Type | Default | Rules |
|---|---|---|---|
driver |
"local" |
"local" |
Only local exists in v1 |
backup |
VolumeBackup? |
null |
The volume must be mounted by a service |
A local volume lives on one worker. It is created there by the first replica of the service that mounts it and stays bound to that worker. orch never creates an empty replacement elsewhere; see local volumes.
volumes {
["database"] {}
}VolumeBackup
| Field | Type | Default | Rules |
|---|---|---|---|
schedule |
String | "0 3 * * *" |
Five UTC cron fields |
keep |
Int | 7 |
1 to 365 scheduled backups kept on the worker |
before |
Listing<String> |
empty | Command run in the owning service's container first |
volumes {
["world"] {
backup = new VolumeBackup {
schedule = "0 */6 * * *"
keep = 8
before { "rcon-cli"; "save-all" }
}
}
}Changing backup never restarts the service. See
volume backups.
Database
Postgres, MySQL, MariaDB, MongoDB, Redis, Valkey, Dragonfly,
Garnet, ClickHouse and LibSQL each run that
engine as a service of the same name, with a NAME-data volume, generated
credentials and optional scheduled backups. Names are at most 54 characters.
| Field | Type | Default | Rules |
|---|---|---|---|
version |
String | per engine | Tag of the official image |
image |
String? | null |
Full image reference instead |
resources |
Resources |
per engine | |
constraints |
Mapping<String, String> |
empty | Node labels |
backup |
DatabaseBackup? |
null |
new DatabaseBackup {} backs up at 03:00 UTC and keeps 7 |
databases {
["main"] = new Postgres {
version = "17"
backup = new DatabaseBackup {}
}
["cache"] = new Redis {}
}See Databases for credentials, backups and restore.
CronJob
A scheduled one-shot workload. Each entry under cronJobs is a CronJob.
Cron jobs are described in detail in jobs and schedules.
| Field | Type | Default | Rules |
|---|---|---|---|
image |
String | required | Valid OCI reference, at most 1024 bytes |
schedule |
String | required | Exactly five cron fields, evaluated in UTC |
command |
Listing<String> |
image default | At most 256 entries |
args |
Listing<String> |
image default | At most 256 entries |
resources |
Resources |
100m, 128Mi |
Same rules as services |
env |
Mapping<EnvironmentName, String> |
empty | At most 256 entries |
secretEnv |
Mapping<EnvironmentName, DnsLabel> |
empty | At most 256 entries |
connect |
Mapping<EnvironmentName, DatabaseName> |
empty | At most 20; see Databases |
secretFiles |
Listing<SecretFile> |
empty | At most 64 |
dependsOn |
Listing<DnsLabel> |
empty | Services of this application |
constraints |
Mapping<String, String> |
empty | Required node labels |
startDeadline |
Duration | "1m" |
1s to 1h |
timeout |
Duration | "15m" |
10s to 24h |
mounts |
Listing<Mount> |
empty | Every mount readOnly = true; see below |
Schedule rules:
- Exactly five fields: minute, hour, day of month, month, day of week.
- Always UTC.
CRON_TZ=andTZ=prefixes are rejected. - Descriptors such as
@dailyand six-field expressions with seconds are rejected. - No leading or trailing spaces; at most 256 bytes.
Cron mount rules:
- Each mount must set
readOnly = true. The Pkl type rejects it otherwise. - Each source must be a declared volume that a service in this application mounts.
- All mounts of one job must belong to the same service.
- A mount target cannot repeat another mount or secret file target.
cronJobs {
["nightly-report"] {
image = "ghcr.io/acme/reports:1.0"
schedule = "30 2 * * *"
args { "--since" "24h" }
secretEnv {
["DATABASE_URL"] = "database-url"
}
timeout = "30m"
}
}Notification
Slack, Discord and Webhook send an application's events to a webhook.
| Field | Type | Default | Rules |
|---|---|---|---|
url |
DNS label | required | Name of the application secret holding the webhook URL |
on |
Listing<String> |
empty, meaning the failures | deploy.succeeded, deploy.failed, deploy.rolled_back, backup.failed, cron.failed, replica.unhealthy |
notifications {
new Slack { url = "slack-webhook" }
}See Notifications.
Deployment
The deploy block controls rolling updates.
| Field | Type | Default | Rules |
|---|---|---|---|
maxSurge |
Int | 1 |
0 to 100 extra replicas during a rollout |
maxUnavailable |
Int | 0 |
0 to 100 replicas that may be unavailable |
healthDeadline |
Duration | "2m" |
10s to 1h for replacements to become ready |
autoRollback |
Boolean | true |
Restore the last healthy revision on failure |
autoUpdate |
Boolean | false |
Redeploy when an image tag points to a new digest; see automatic image updates |
preDeploy |
PreDeployHook? |
null |
Job that must succeed before rollout |
maxSurge and maxUnavailable cannot both be 0. An application that
publishes node-local ports must set maxSurge = 0. See
rollouts and deployments.
PreDeployHook
| Field | Type | Default | Rules |
|---|---|---|---|
service |
DNS label | required | A service in this manifest |
command |
Listing<String> |
required | 1 to 256 entries |
args |
Listing<String> |
empty | At most 256 entries |
timeout |
Duration | "15m" |
10s to 24h |
The hook runs as a one-off job with the image, environment, secrets,
resources, constraints and dependencies of the named service from the new
revision. The new revision rolls out only after it exits with 0. Details and
failure handling are in jobs and schedules.
deploy {
preDeploy = new PreDeployHook {
service = "web"
command { "./bin/migrate" }
args { "up" }
timeout = "5m"
}
}Composing manifests
Pkl modules can import other modules, so shared defaults and conventions live in one place instead of being copied between applications.
Local modules
Imports of local files are allowed as long as they stay inside the evaluation root. The root defaults to the directory that contains the manifest. Symlinks are resolved before the check.
A shared module can export functions or templates:
// lib/web.pkl
import "https://orch.torsten.work/pkl/v1/Application.pkl"
function web(imageRef: String, domain: String): Application.Service = new {
image = imageRef
replicas = 2
resources {
cpu = "250m"
memory = "256Mi"
}
http = new Application.Http {
port = 8080
domains { domain }
healthPath = "/healthz"
}
}// orch.pkl
amends "https://orch.torsten.work/pkl/v1/Application.pkl"
import "lib/web.pkl"
name = "shop"
services {
["web"] = web.web("ghcr.io/acme/shop:2.3.0", "shop.example.com")
}Name function parameters differently from the properties they set. Inside
new { image = image },imagerefers to the property being defined, which makes Pkl recurse until it overflows the stack.
Within one file, a local value and Pkl's amend syntax remove repetition:
amends "https://orch.torsten.work/pkl/v1/Application.pkl"
name = "shop"
local base = new Service {
image = "ghcr.io/acme/shop:2.3.0"
env { ["APP_ENV"] = "production" }
secretEnv { ["DATABASE_URL"] = "database-url" }
}
services {
["web"] = (base) {
replicas = 2
http = new Http {
port = 8080
domains { "shop.example.com" }
healthPath = "/healthz"
}
}
["worker"] = (base) {
command { "/app/bin/worker" }
}
}For per-environment files, one manifest can amend another. Values that are not overridden come from the base:
// production.pkl
amends "orch.pkl"
services {
["web"] {
replicas = 4
}
}When a manifest imports modules from a parent directory, set a wider root:
orch validate -f apps/shop/orch.pkl --root .
orch deploy -f apps/shop/orch.pkl --root . --waitA module outside the root fails with
Refusing to load module ... because it is not within the root directory.
HTTPS modules
Modules can also be imported from https: URLs, which lets several
repositories share one set of conventions:
amends "https://orch.torsten.work/pkl/v1/Application.pkl"
import "https://modules.example.com/orch/v3/web.pkl"The first evaluation records each remote module's SHA-256 in orch.lock
next to the manifest, the same way for orch deploy, orch plan and the
other commands that read it. Commit that file. From then on a module whose
contents change on its server stops the evaluation with an error that names
it, so nobody who controls that server can change what you deploy. To accept
a new version, delete its line from orch.lock and run the command again.
The orch schema itself is built into orch and never pinned.
Pointing the URLs at an immutable release or commit still helps: it keeps the lock file valid across machines. Imported modules are trusted code that runs on your workstation and can make requests to any HTTPS service it can reach.
What evaluation may not do
To keep manifests reproducible and keep workstation data out of desired state, evaluation denies:
- all resource reads, including
read("env:..."),read("prop:...")andread("file:..."); - plain
http:modules,package:and project packages, and module paths; - local files outside the evaluation root.
Your environment variables, external properties, Pkl settings and package caches are not passed to the evaluator. To vary a value per environment, keep one manifest per environment and amend a shared base, as shown above. Keep sensitive values out of manifests entirely and use secrets.
Schema and editor support
orch schema prints the embedded schema, the authoritative source for this
page:
orch schema > Application.pklEditors with the Pkl extension (VS Code, IntelliJ, Neovim and others using
pkl-lsp) resolve the amends URL directly, so completion, documentation and
type errors work without any setup. orch itself never fetches that URL: it
evaluates against the schema embedded in the binary, so manifests work offline
and always match the CLI version you run. Stock pkl eval also resolves the
URL.
Manifests written before orch 1.0 amend
https://orch.torsten.work/pkl/v1alpha1/Application.pkl. That schema is v1
under its old name, so those manifests keep working unchanged across 1.x;
switch the URL to v1 whenever convenient. amends "orch:/v1alpha1/Application.pkl" and the earlier
https://raw.githubusercontent.com/TorstenDittmann/orch/main/pkl/v1alpha1/Application.pkl
URL also keep working, but editors cannot resolve the orch: scheme.
pkl eval shows the evaluated module, but only orch validate applies orch's
additional rules. Use orch render to see exactly what would be sent to the
controller.