The field tables are in the IaC reference, generated from the schema. This page keeps one worked example per kind and the rules around it.
A file holds one or more YAML documents separated by ---. Every document has the same envelope:
The JSON Schema is also served at GET /api/v1/apply/schema. Point your editor at it for completion. Errors are reported with file and line: infra/web.yaml:14: additional properties 'prot' not allowed (spec.service.prot).
An App’s spec.service is the app.yaml service definition, validated by the same schema. The document schema embeds the app.yaml definitions unchanged, with two additions: an env value may be { secretRef: NAME }, or { from: { database: NAME, field: url } } to read a value from a Database (see Database references).
Project
Environment
Environments belong to a project. Identity is project plus name.
Tag
Export prints every tag, including tags no app uses.
Database
Engine and version cannot change through apply: databases hold data, so a mismatch is reported as an error and you recreate it deliberately. Backups, resources and public access are still managed with their own commands.
App
Apply manages apps that run a prebuilt image (build.type: image). Git builds are configured with a git source, not here. port, health.readiness and health.liveness are applied as written. Not supported yet, and rejected with a clear error: host-path volumes, egress policies, GPU requests, registry credentials and vault env references. A live app that uses them keeps them when you apply; the plan warns.
Database references
{ from: { database: NAME, field: FIELD } } points an env var at a Database’s connection details. field is one of url (the default), host, port, username, password or database. The app.yaml string form { from: main-db.url } is accepted too.
The value is never read by apply. Apply records the reference (the same connection the dashboard’s Connect button makes), and the control plane fills in the value when it creates the container. So the files, the plan, the plan hash and stack revisions only ever hold main-db.url, never the password or the URL. The database must exist or be declared in the same files; the plan shows the reference as connections.DATABASE_URL: main-db.url and lists the database under dependsOn, and databases are always applied before apps. If the live app also has a literal or secret value under the same name, the plan warns so you can remove it.
Volumes
service.volumes lists named volumes (name, path). Apply matches them by name through PUT /api/v1/apps/{name}/volumes: a new name is attached, a changed path is updated, and the plan shows volumes.data: /data. Host-path bind mounts are rejected, so the files can never mount a host directory. Volumes that the files do not list are kept, and detached only by prune on an app the source manages. Detaching never deletes the Docker volume or its data; deleting data is a separate, explicit action. Mounts are fixed when the container is created, so a volume change restarts the app unless --no-deploy is set, and the app shows a pending config change until then. An app document without a volumes key never touches the app’s volumes.
Published ports and restart
service.published_ports binds ports straight on the host beside the routed port, for UDP services such as DNS or WireGuard. Each entry is container_port, host_port and protocol (tcp, the default, or udp), the same shape as app.yaml and the API. A port out of range, a protocol other than tcp or udp, or the same host port and protocol twice is rejected before the plan. Apply runs the same host port admission as POST /api/v1/apps: a port another app already publishes, a reserved port, or a service placed on a remote node fails the apply with the API’s own message, and nothing is saved for that app.
service.port may be left out when the service has at least one published_ports entry (a UDP-only DNS or VPN app). A service with domains still needs a port, since the proxy routes HTTP to it, and a service with neither a port nor published_ports is rejected.
service.build.registryCredential names an existing registry credential used for private pulls. It is a reference only, never a secret value, and credentials are not a managed kind: create one first with registry-credentials create. A name the control plane does not list fails the plan with registry_credential_not_found. Changing the name is drift and shows as an update, and removing the line clears the credential. An export writes the name back.
service.dns.names (beta) lists extra internal names under the mesh zone that resolve like the app name, for example [shop, www.shop]. Lowercase letters, digits and hyphens only, no wildcards, and no name another app uses. It needs the runtime setting dns.internal_names_enabled; limits come from the dns.internal_* settings. An app document without dns leaves the live names alone; names: [] clears them. A name taken by an app outside the files is refused at apply with dns_name_conflict.
service.restart takes no, on-failure or on-failure:N for a service that runs to completion (a migration or seed job), and always or unless-stopped. The plan shows changes as publishedPorts and restart, an out-of-band change to either is drift, and revisions and rollbacks keep both. An app document without published_ports or restart leaves the live values alone; published_ports: [] clears the ports.
Rollout policy
service.rollout sets max_surge, max_unavailable and min_available (each an integer such as 2 or a percent such as 25%). Apply saves it through PUT /api/v1/apps/{name}/rollout, the same policy a spec deploy and levelrail-cli rollout status read, and export prints it back. The plan shows rollout.min_available: 1 -> 2. Fields left out inherit the APP_ROLLOUT_* env defaults. An app document without a rollout key never touches the saved policy; DELETE /api/v1/apps/{name}/rollout returns an app to the defaults.
Inline files
service.files lists text files written into the container (path, content, optional mode). Apply sets each one through PUT /api/v1/apps/{name}/files and removes live files the list omits, so a declared list owns the app’s non-secret files; export prints them back. Secret files are rejected in documents, because their content would sit in git: set them from the dashboard or CLI, and apply leaves them alone. Files are fixed at container create, so a change restarts the app unless --no-deploy is set. An app document without files never touches them.
Pre-deploy snapshot policy, the CI gate of a git source and the heartbeat monitor are instance or git-source settings, not part of an App document yet; manage them from the dashboard, CLI or API.
Scheduled jobs
service.jobs is the app.yaml jobs list. Apply matches jobs by name: a new name is created, a changed one is updated in place (its run history is kept). Jobs created in the dashboard or CLI that the files do not list are kept, and removed only by prune on an app the source manages. A job that the app’s own app.yaml declares is left alone with a warning, so each job has one owner. An app document without a jobs key never touches the app’s jobs.
Domain
Adds a hostname to an app. It is additive with the App’s own domains, and a hostname can belong to one app only. Export folds domains into each App’s service.domains and does not print Domain documents.
LoadBalancer
metadata.name is the app. The spec is the app.yaml loadbalancer block.
Pipeline
The pipeline definition is validated with the same checks as pipelines validate, and issues point at the line inside your file. A pipeline synced from the repository cannot be changed here.
AlertRule
Importing compose projects
levelrail-cli import compose-ref [dir] scans a directory for docker-compose*.yml, compose*.yaml and similar files. It is read only: nothing is written unless you pass --write DIR, and existing files are kept unless you also pass --force. The output is checked with the same loader stack plan uses before it is printed or written. It has two modes.
- Reference (
--reference): one App per compose file with spec.compose.path. The file is never copied, so there is one definition. See Compose projects as code. Needs the beta setting iac.compose_refs.
- Convert (default): prints Apps for every image based service. The compose file and the documents are then two definitions of the same app: keep one.
- Environment values are never read into the output. In convert mode every variable becomes a secret name listed in
SECRETS.md; env_file contents are not read either.
- In convert mode a service with a
build: context is skipped with a note, because apply runs prebuilt images. Volumes, profiles, and command overrides are listed in MIGRATION.md, not emitted.
- Scanning stops at
LEVELRAIL_IMPORT_COMPOSE_MAX_DEPTH folders (default 4), skips files over LEVELRAIL_IMPORT_COMPOSE_MAX_BYTES (default 1 MiB), and never follows symlinks.
Discovery by the com.docker.compose.project container label is not available yet. Last modified on November 17, 2026