shc.yaml
Layer 6. Services. Services
New line, in development. This page describes SHC as it is on the
devbranch, not the released product. See The new line.
shc.yaml is the recommended way to write an app’s services. It sits in the app directory in place of compose.yaml, beside app.yaml, vars.yaml, backup.yaml and the plug, socket and job files, which stay as they are. Every key in it is something SHC honours. Nothing is reinterpreted, and a key the schema does not name stops the install with a coded error that names the service and the key.
compose.yaml stays fully supported as the import path: an app you already have as a compose file, a foreign platform’s app, or what an importer writes, with its x-shc-* keys (What SHC does to your compose file). When an app directory holds both files, shc.yaml is the app and compose.yaml is not read. The install says so with X200538SHYTWO.
A small app
Section titled “A small app”services: web: image: "{{ vars.image }}" primary: true expose: [8080] environment: ADMIN_EMAIL: "{{ vars.adminEmail }}" volumes: - name: data path: /var/lib/web - source: ./files/web.conf path: /etc/web/web.conf read_only: true quota: cpu: "0.5" memory: 256M healthcheck: test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/healthz"] interval: 10s retries: 5expose declares the port web listens on and nothing more. A deployment publishes it: shc install ./apps/web -s web --expose web.example.com routes that hostname to the primary service, and --expose 8443=web:8080 publishes a port. data is a named volume, so there is no top-level volumes: block; the render declares it. ./files/web.conf is a file in the app directory. quota is what deploy.resources was in compose.
How it is read
Section titled “How it is read”The file is a Jinja2 template, strict on undefined names, with the same context a compose template gets (vars, integrations, hosts, url(), shc). It renders first, and the schema applies to the rendered document, so a key that an untaken {% if %} never wrote is not there. A group is a {% members %} block, the one way to write numbered members. Scaling stays --scale db=N.
shc.yaml and compose.yaml produce the same stored specification, so there is one renderer and every later step (pods, replica projects, placement, backups) is the same for both. An app’s compose file and its shc.yaml twin store the same spec digest for every replica.
What is refused
Section titled “What is refused”| Code | Refused |
|---|---|
X400530SHYUNK | A key the schema does not name. |
X400531SHYCMP | A compose key shc.yaml does not take, such as ports or deploy. The error says what to write instead where there is something. |
X400532SHYXSH | Any x-shc-* key. The error names the plain key that replaces it. |
X400533SHYPRT | A host side on a port, such as "8080:80" under expose. |
X400534SHYHST | A mount whose source is a host path. |
X400535SHYVAL | A value SHC cannot honour, such as access: rwx or a list of KEY=value under environment. |
X400536SHYPRV | Anything in the privileged class written outside privileges:. |
X400537SHYDOC | A rendered document that is not one YAML mapping. |
Top-level keys
Section titled “Top-level keys”| Key | Type | Meaning |
|---|---|---|
services | mapping of name to service | The app’s services. |
secrets | mapping of name to secret | Secrets a service can list. Each has one key, vault, a ref+vault://... reference; the value is never in the file. |
configs | mapping of name to config | Inline configs: content (the bytes) and an optional engine name. |
where | list of where terms | Where the deployment may run. Each entry is one term of the --where selector: node=<hostname>, <label>=<value>, <label>!=<value>. |
service_selectors | mapping of name to selector, or to select, route and scope | Names the deployment answers under. Each goes to the replicas whose labels match its selector, exactly one of them when the value ends in :1, picked by its route: nearest (the default), any or local. Compose writes it as x-shc-service-selectors (x-shc directives). |
Service keys
Section titled “Service keys”The compose column is the key it replaces, for an author coming from a compose file.
| Key | Type | Meaning | Compose |
|---|---|---|---|
image | string | The image the replica runs. | image |
command, entrypoint | string or list of string | same | |
working_dir, user, hostname, domainname, platform | string | same | |
environment | mapping of string to string | Only the mapping form. | environment |
env_file | list of string | Files in the app, each written from the app directory: ./web.env is web.env beside shc.yaml. A path that leaves the app is refused. The file is stored with the app and every node that runs a replica reads its own copy, so a secret belongs in secrets. | env_file, where the same file is app/web.env |
expose | list of port | Listening ports only: an integer, or a string holding a port or port/protocol. A quoted port is a port, since a template has to quote a number. A primary or path service writes the port it is routed to as a number: SHC reads that port before the variables render, so a template there is refused (X400939HSTPRP, X400940HSTSEC) by shc validate and install alike. | expose and ports |
labels | mapping of string to string | Plain labels. A key starting with shc. is refused. | labels |
networks | list of name, or mapping | A mapping entry may set aliases. | networks |
depends_on | list of name, or mapping of name to condition, required, restart | The list form means started, required. condition is started, healthy or completed. | depends_on, with service_started, service_healthy, service_completed_successfully |
healthcheck | test, interval, timeout, retries, start_period, disable | The check the runtime runs. | healthcheck |
health.restart_after | duration, or 0 | How long a container may stay unhealthy before its node restarts it. 0 turns it off. | x-shc-health |
restart | no, always, on-failure or unless-stopped | The policy the node agent applies. Absent means unless-stopped. | restart and deploy.restart_policy |
replicas | integer | Replica count when --scale does not name this service. Absent means 1. | deploy.replicas and an integer scale |
scale.max | integer, 1 or more | The replica ceiling. A pod’s ceiling is the smallest its members state. | x-shc-scale.max |
scale.backup | integer | Replica count while a backup runs, usually 0 or 1. Absent leaves the service as it is. A word such as keep, min or max is refused. | x-shc-scale.backup |
scale.witness | group name | The group this service witnesses, from outside its members block. A group the app does not have, or a member declaring it, is refused. Groups. | x-shc-scale.witness |
quota.cpu, quota.memory | quantity | The quota. The container limit is the quota times the limit ratio. | deploy.resources.limits |
quota.cpu_reservation, quota.memory_reservation | quantity, optional | What the service reserves. Absent means the quota times the reservation ratio. | deploy.resources.reservations |
primary | bool, or a port from 1 to 65535 | The service a bare hostname routes to. A port picks which listening port. | x-shc-primary |
path | absolute URL path, not / | The path this service serves under the primary’s hostname. | x-shc-path |
path_strip | bool | The edge strips path before it dials the service. Needs path. | x-shc-path-strip |
upstream_tls | port, ca, server_name | A port the service serves over TLS only. The edge dials it over HTTPS, trusting the ca PEM alone and checking server_name. | x-shc-upstream-tls |
live_labels | mapping of label key to test, interval, timeout | Commands SHC runs in each replica. The first line one prints is that replica’s label value, which where and the top-level service_selectors can then select on. | x-shc-live-labels |
volumes | list of mount | See Mounts. | volumes and x-shc-volumes |
tmpfs | string or list of string | A tmpfs mount. | tmpfs |
shm_size | string or integer | shm_size | |
cap_add | list of string | Capabilities in the runtime’s default set. An escalating one goes under privileges. | cap_add |
security_opt | list of string | Options that keep confinement on. An unconfined one goes under privileges. | security_opt |
privileges | mapping | See Privileges. | |
extra_hosts | list of string, or mapping | extra_hosts | |
pull_policy, stop_grace_period, stop_signal | string | same | |
group_add, dns, dns_search | list of string | same | |
oci_runtime | string | The OCI runtime, such as nvidia. SHC’s own runtime is the node’s, not this. | runtime |
init, read_only, tty | bool | Without tty: true a replica’s first process starts with stdin on /dev/null and its output on pipes, as docker starts it, on every runtime. | same |
sysctls, ulimits | mapping | A tenant app may not set a host sysctl. | same |
pre_start, post_start | list of hook | Each hook takes command (required), user, working_dir and environment. | same |
secrets | list of secret name | secrets | |
configs | list of config name, or {name, path} | The config is a file at path, or at /<name> without one. A read_only service takes it too: SHC writes the file on the node that runs the replica and mounts it read-only. | configs |
network_mode | none, host or service:<name> | service:<name> puts both services in one pod. A tenant app may not say host. | network_mode |
pid, ipc | host or service:<name> | service:<name> is the same pod grouping. For ipc, SHC starts the service you name with a shareable IPC namespace, so the two share it on a docker node with nothing more to write. A podman node cannot share either: its podman-compose reads no ipc key and hands pid to podman, which has no service: mode, so SHC keeps the pod on docker nodes and refuses it on a podman one with X400797EXEPDM, see compose keys. | same |
volumes_from | list of service name | The service joins that service’s pod. | volumes_from |
links | list of service or service:alias | links |
scale.restore, http_ui and healthcheck.start_interval are refused. Which volumes are durable is still backup.yaml’s to say.
Mounts
Section titled “Mounts”Each entry of a service’s volumes is a mapping. It has a name or a source, never both.
| Field | Type | Meaning |
|---|---|---|
name | string | A named SHC volume. Two services that name the same volume share it. A path in the name (data/uploads) would sit inside another volume and is refused X403334VOLNST. |
source | ./... or /etc/shc/<name> | A file or directory in the app directory, or a platform mount such as /etc/shc/tls.ca. Any other absolute path is a host path and refused. |
path | absolute path | Where it is mounted in the container. |
read_only | bool | |
mode | octal string | The mode the volume’s directory gets before the service starts. |
owner | uid:gid | Its owner, both numbers or both names. |
noinit | bool | Do not seed the volume from the image. |
size | quantity | A block volume’s size. Named volumes only. |
access | rwo or rox | Default rwo. Named volumes only. |
Privileges
Section titled “Privileges”The Docker socket, privileged, escalating capabilities, unconfined security options and host devices are asked for in one block, privileges. Written anywhere else they are refused, and the error names this block.
services: runner: image: "{{ vars.image }}" privileges: docker_socket: true| Field | Type | Meaning |
|---|---|---|
docker_socket | true, false or read_only | A Docker socket at /var/run/docker.sock: the deployment’s own broker socket, never the host’s. See The Docker socket. |
privileged | bool | |
cap_add | list of string | Capabilities outside the runtime’s default set. |
security_opt | list of string | Unconfined options, such as apparmor:unconfined. |
devices | list of string | Host devices. |
A socket for the package’s own containers only is declared in app.yaml, privileges.docker_socket: self, and then needs no grant (see The Docker socket). Otherwise the block only asks. The install is refused X403990HSTGNT until the master tenant’s operator grants the deployment each class it asks for, socket, privileged, caps, confinement or devices, with shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> <classes>, the same grant that admits these in a compose file. An app.yaml waiver declares a need and admits nothing.
Groups
Section titled “Groups”Numbered members are a {% members %} block, as in a compose template:
services:{% members "db", default=3, max=5 as m %} db-{{ m.n }}: image: postgres:17 environment: MEMBER: "{{ m.n }}" volumes: - name: data-{{ m.n }} path: /var/lib/postgresql/data expose: [5432]{% endmembers %}data-{{ m.n }} is one named volume per member. Groups covers the block, the member object and --scale db=<location>:N.
From compose.yaml: shc convert
Section titled “From compose.yaml: shc convert”shc convert prints the shc.yaml an app’s compose.yaml becomes. It writes nothing.
shc convert ~/my-apps/feedback > ~/my-apps/feedback/shc.yamlIt edits the template’s own text, and only the lines that change. Every {{ }} stays where it was and every {% %} line stays between the same entries, so the shc.yaml renders, branch for branch, what the compose template rendered. x-shc-* keys become their plain keys, ports become expose, deploy becomes replicas, quota, restart and where, each volume becomes a mount entry, an env_file under app/ is written from the app directory, the privileged class moves into privileges, and depends_on conditions take the short words.
What shc.yaml has no key for is left out, and each one is a warning on stderr:
warning: service web published 8080 on the host as 80; shc.yaml exposes 80, and a deployment publishes it with --exposewarning: service web's logging is not carried: shc.yaml has no such keyIt exits 1 when there is any warning, so a script can tell the output needs a look, and 0 when it carried everything. -o json prints shc_yaml and notes as one document.
While compose.yaml is still in the directory, an install reads shc.yaml and says the compose file was not read. Delete compose.yaml once you are happy with the result.