Skip to content
SHC Docs

shc.yaml

Layer 6. Services. Services

New line, in development. This page describes SHC as it is on the dev branch, 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.

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: 5

expose 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.

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.

CodeRefused
X400530SHYUNKA key the schema does not name.
X400531SHYCMPA compose key shc.yaml does not take, such as ports or deploy. The error says what to write instead where there is something.
X400532SHYXSHAny x-shc-* key. The error names the plain key that replaces it.
X400533SHYPRTA host side on a port, such as "8080:80" under expose.
X400534SHYHSTA mount whose source is a host path.
X400535SHYVALA value SHC cannot honour, such as access: rwx or a list of KEY=value under environment.
X400536SHYPRVAnything in the privileged class written outside privileges:.
X400537SHYDOCA rendered document that is not one YAML mapping.
KeyTypeMeaning
servicesmapping of name to serviceThe app’s services.
secretsmapping of name to secretSecrets a service can list. Each has one key, vault, a ref+vault://... reference; the value is never in the file.
configsmapping of name to configInline configs: content (the bytes) and an optional engine name.
wherelist of where termsWhere the deployment may run. Each entry is one term of the --where selector: node=<hostname>, <label>=<value>, <label>!=<value>.
service_selectorsmapping of name to selector, or to select, route and scopeNames 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).

The compose column is the key it replaces, for an author coming from a compose file.

KeyTypeMeaningCompose
imagestringThe image the replica runs.image
command, entrypointstring or list of stringsame
working_dir, user, hostname, domainname, platformstringsame
environmentmapping of string to stringOnly the mapping form.environment
env_filelist of stringFiles 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
exposelist of portListening 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
labelsmapping of string to stringPlain labels. A key starting with shc. is refused.labels
networkslist of name, or mappingA mapping entry may set aliases.networks
depends_onlist of name, or mapping of name to condition, required, restartThe list form means started, required. condition is started, healthy or completed.depends_on, with service_started, service_healthy, service_completed_successfully
healthchecktest, interval, timeout, retries, start_period, disableThe check the runtime runs.healthcheck
health.restart_afterduration, or 0How long a container may stay unhealthy before its node restarts it. 0 turns it off.x-shc-health
restartno, always, on-failure or unless-stoppedThe policy the node agent applies. Absent means unless-stopped.restart and deploy.restart_policy
replicasintegerReplica count when --scale does not name this service. Absent means 1.deploy.replicas and an integer scale
scale.maxinteger, 1 or moreThe replica ceiling. A pod’s ceiling is the smallest its members state.x-shc-scale.max
scale.backupintegerReplica 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.witnessgroup nameThe 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.memoryquantityThe quota. The container limit is the quota times the limit ratio.deploy.resources.limits
quota.cpu_reservation, quota.memory_reservationquantity, optionalWhat the service reserves. Absent means the quota times the reservation ratio.deploy.resources.reservations
primarybool, or a port from 1 to 65535The service a bare hostname routes to. A port picks which listening port.x-shc-primary
pathabsolute URL path, not /The path this service serves under the primary’s hostname.x-shc-path
path_stripboolThe edge strips path before it dials the service. Needs path.x-shc-path-strip
upstream_tlsport, ca, server_nameA 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_labelsmapping of label key to test, interval, timeoutCommands 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
volumeslist of mountSee Mounts.volumes and x-shc-volumes
tmpfsstring or list of stringA tmpfs mount.tmpfs
shm_sizestring or integershm_size
cap_addlist of stringCapabilities in the runtime’s default set. An escalating one goes under privileges.cap_add
security_optlist of stringOptions that keep confinement on. An unconfined one goes under privileges.security_opt
privilegesmappingSee Privileges.
extra_hostslist of string, or mappingextra_hosts
pull_policy, stop_grace_period, stop_signalstringsame
group_add, dns, dns_searchlist of stringsame
oci_runtimestringThe OCI runtime, such as nvidia. SHC’s own runtime is the node’s, not this.runtime
init, read_only, ttyboolWithout 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, ulimitsmappingA tenant app may not set a host sysctl.same
pre_start, post_startlist of hookEach hook takes command (required), user, working_dir and environment.same
secretslist of secret namesecrets
configslist 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_modenone, host or service:<name>service:<name> puts both services in one pod. A tenant app may not say host.network_mode
pid, ipchost 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_fromlist of service nameThe service joins that service’s pod.volumes_from
linkslist of service or service:aliaslinks

scale.restore, http_ui and healthcheck.start_interval are refused. Which volumes are durable is still backup.yaml’s to say.

Each entry of a service’s volumes is a mapping. It has a name or a source, never both.

FieldTypeMeaning
namestringA 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.
pathabsolute pathWhere it is mounted in the container.
read_onlybool
modeoctal stringThe mode the volume’s directory gets before the service starts.
owneruid:gidIts owner, both numbers or both names.
noinitboolDo not seed the volume from the image.
sizequantityA block volume’s size. Named volumes only.
accessrwo or roxDefault rwo. Named volumes only.

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
FieldTypeMeaning
docker_sockettrue, false or read_onlyA Docker socket at /var/run/docker.sock: the deployment’s own broker socket, never the host’s. See The Docker socket.
privilegedbool
cap_addlist of stringCapabilities outside the runtime’s default set.
security_optlist of stringUnconfined options, such as apparmor:unconfined.
deviceslist of stringHost 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.

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.

shc convert prints the shc.yaml an app’s compose.yaml becomes. It writes nothing.

Terminal window
shc convert ~/my-apps/feedback > ~/my-apps/feedback/shc.yaml

It 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 --expose
warning: service web's logging is not carried: shc.yaml has no such key

It 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.