What SHC does to your compose file
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.
A compose file is the import path. A new app is written as shc.yaml, where every key is honoured as written, and shc convert turns an app’s compose.yaml into one.
This page lists the keys and page verdicts in ce core/composenorm.Table(). The verdict describes the render; each runtime may refuse keys it cannot run:
- honoured: the key reaches the runtime as you wrote it.
- reinterpreted: the render rewrites it into something else. The table says into what.
- dropped: the render removes or overrides it, with a warning where it says one.
- refused: the render stops with the code shown.
- read: SHC or a runtime consumes an extension key; the row says how.
Silent drops are listed under Gaps.
Checked against shc 3c88a263038b, which pins ce db676cf4aa0b, on 2026-10-05. Every reference below is a ce path unless it says shc.
The short version
Section titled “The short version”- Your
compose.yamlis a Jinja template. It renders first; everything on this page applies to the rendered text. - The rendered text must be one plain YAML document: no
include, noextendsfrom another file, nolabel_file, no!reset/!overridetags,<<only as a plain merge key. A module that has any of these is read through compose’s own loader at render, with no environment and no interpolation, and the plain document it returns is what installs (core/composenorm/loader.goNormalisePackage). A tenant’s own app or an adapter’s import that has any of them is refusedX400126CMPNRM(core/composenorm/composenorm.goNotPlain), except alabel_fileinside the package, whose labels the render writes into the service (modules/app/compose_label_file.goInlineLabelFiles). - Volumes are reinterpreted. Every named volume becomes a bind of a directory SHC owns (or of a provisioned block volume), and the top-level declaration goes away. Absolute host paths are refused except the four inert files and the granted or platform mounts listed below.
ports:only declares a container port. The host side is never published; it renders asexpose:. A deployment publishes or routes with--expose.deploy:is a closed set.mode: replicated/global,replicas,resources.limits/reservations(cpus, memory, plus limits.pids),restart_policy.condition,update_configandrollback_configare read;labelsandplacement.constraintsare translated with a warning; every other key in that block is refusedX400941SWMVOC.deploy.resources.limitsis read as the service’s quota. The limit the container runs under is quota x 1.5 by default, and a reservation of quota x 1.0 is added. See the resource model.restart:keeps its meaning but moves: the runtime getsrestart: "no"and the node agent applies your policy. Restart behaviour says what brings a replica back.- SHC stamps its own
shc.*labels; authored ones are refusedX400357LBLSHC. A route comes from--expose. An authoredtraefik.*label is refusedX400358LBLTRF. - An app a tenant brings from its own repo goes through a stricter closed set on top of all this (
modules/app/package_trust_compose.go); the Tenant app notes below say where.
The order things happen
Section titled “The order things happen”An install or update renders once, on the cluster leader (an install from a path or an archive renders on its placed node, which holds the bytes). An app author does not render per node. The leader finishes that stored render for another node (Groups: where members run). The steps below are modules/app/install_runner.go ExecuteCompose:
- Jinja render, strict on undefined names (
X400998TPLUND); a group’s{% members %}block is stamped here. A module whose rendered text is not plain is then read through compose’s own loader into a plain document (update_funnel.go,NormaliseRenderedwith the package directory). - Tenant app only: the tenant gate (
refuseTenantPackageCompose,X403996TNTCMP). - Plain-document gate and long-to-short mount rewrite (
NormaliseRendered,X400126CMPNRM). - Closed deploy set:
portstoexpose, and thedeploy:keys above (swarm_vocabulary.goTranslateSwarmVocabulary). - Checks:
update_config(RefuseUpdateConfig), configs (RefuseHostConfigs), labels (RefuseUnlabelled). - Secrets staged from the vault into RAM (
StageComposeSecrets). - Injections: integration networks and aliases,
shc.*labels, log rotation, OTel env, Traefik, the tenant alias on every network off theshcfabric,--exposepublishes, the node resolver. x-shc-*lint (ValidateComposeExtensions), replica ceiling,--scaleand quotas, restart, CA trust, mount digests.- Volumes resolved to host paths (
ResolveAndPrepVolumesWithDurability), networks declared and pinned (AutoDeclareNetworks,ApplyFabricTarget,PinDeploymentNetworks). - The document is split into one compose project per replica. The render checks the document and projects against the render node’s runtime (
ReplicaProjects,RefuseForRuntime); the stored spec records refusals from each runtime (runtimeRefusals).
What a node runs depends on the cluster. A Linux node of a cluster on the shc fabric whose service VIPs run (the fabric clear of the VIP range), or a Mac node on the apple runtime, runs the replica projects of step 10, one compose project per replica, and never the deployment’s own compose.yaml: an install that does not split is refused (X400085PODPRJ). Anywhere else the node runs the deployment’s own compose.yaml. Each daemon decides during startup, waiting for its identity and fabric state; and shc doctor (pods.replica-projects) says which and why. A fresh install finishes each replica for its admission binding, including a binding on another node, and an ordinary update finishes each for the node its live assignment row binds it to (heldReplicas, SHC-1628). See Groups: where members run.
Runtimes. compose and podman use their compose CLIs. Incus and Apple have explicit key tables: composenorm.Table() records each pass’s verdict, and core/executor/incus/translate.go and core/executor/apple/project.go enforce them. Podman refuses a pid join it could not start and the ipc values its podman-compose drops (core/executor/podman_refuse.go). A document or replica project refused by the render node’s runtime fails the render (X400087PODRTM, modules/app/spec_record.go RefuseForRuntime). The page verdict alone does not promise support on every runtime.
Top-level keys
Section titled “Top-level keys”| Key | Verdict | What SHC does | Code |
|---|---|---|---|
version | honoured | Kept; compose ignores it. | core/pod/project.go Project |
name | dropped | Every deployment runs under SHC’s project name (-p), which overrides yours. | core/runtimecmd/runtimecmd.go, core/executor/executor.go |
include | reinterpreted / refused | Module: compose’s loader reads the included files at render and merges them into one plain document, which SHC then labels and judges like the rest. Tenant app or adapter import: refused X400126CMPNRM, since its services would carry none of the deployment’s labels. Inline them. | core/composenorm/loader.go NormalisePackage, core/composenorm readsPastTheText |
services | honoured | Each key below. | |
networks | reinterpreted | See Networks. | modules/app/deployment_networks.go |
volumes | reinterpreted | Every named volume a service mounts becomes a bind and its declaration is removed. See Volumes. | modules/app/install_runner.go ResolveAndPrepVolumesWithDurability |
configs | reinterpreted / refused | Only inline content: (plus name, labels). file and environment are refused X400944CFGHST; external is refused earlier, by that closed set, X400941SWMVOC. A service that consumes a config is rolled when its content changes. | modules/app/compose_configs.go RefuseHostConfigs, swarm_vocabulary.go TranslateSwarmVocabulary, mount_digest.go |
secrets | reinterpreted / refused | Only x-shc-vault (and name). The value is resolved from the vault into a RAM-backed file and file: points there; the rendered compose keeps the reference, never the value. file and environment are refused X400942SECSRC; external is refused earlier, by that closed set, X400941SWMVOC. A bad secret name is X400945SECNAM. A service that mounts a secret is rolled when its value moves in the vault: shc update after shc vault set starts again the replicas that mount it, and names the secret. | modules/app/compose_secrets.go stageComposeSecrets, swarm_vocabulary.go TranslateSwarmVocabulary, secret_digest.go |
models | honoured | Passed to compose. Tenant app: refused. | package_trust_compose.go tenantTopLevelKeys |
jobs | honoured | Passed to compose. apple refuses a projection that carries one: a job is the render’s, never a projection’s. | core/executor/apple/project.go |
x-shc-volumes | read | Opts a named volume into a provisioned block volume. See x-shc directives. | core/volume/binding.go |
x-shc-service-selectors | read | Names the deployment answers under, each a service selector going to the replicas it picks by their labels. The old x-shc-aliases is refused for new input. See x-shc directives. | modules/labelcheck, modules/app |
any other x-* | honoured | Compose ignores it. x-podman and x-incus/x-incus-compose are read by those runtimes as their own configuration; the incus executor drops every other x- key. Tenant app: a key a runtime reads beyond compose is refused X403996TNTCMP; an imported app is rejected at import with ADAPTER_REJECT_RUNTIME_EXTENSION. | core/executor/extensions.go ExtensionUses, modules/adapter/gate.go Gate |
Config declarations
Section titled “Config declarations”| Key | Verdict | What SHC does |
|---|---|---|
content | honoured | The inline form the render keeps. |
name | honoured | Kept beside content. Tenant app: refused. |
labels | honoured | |
file | refused | X400944CFGHST. |
environment | refused | X400944CFGHST. |
external | refused | X400941SWMVOC, from that closed set. |
Secret declarations
Section titled “Secret declarations”| Key | Verdict | What SHC does |
|---|---|---|
x-shc-vault | read | The only source. See x-shc directives. |
name | honoured | Kept. Tenant app: refused. |
labels | honoured | |
file | refused | X400942SECSRC, except the path the render itself writes while staging. |
environment | refused | X400942SECSRC. |
external | refused | X400941SWMVOC, from that closed set. |
Secret references
Section titled “Secret references”A long-form entry under a service’s secrets:.
| Key | Verdict | What SHC does |
|---|---|---|
source, target | honoured | The staged file and where it is mounted. |
uid, gid, mode | honoured | Passed through on compose. Incus binds a copy of the staged file for each reference that sets one, owned by that uid and gid inside the instance (root by default) with that mode (0444 by default), written again at every up, so a new value reaches the entry at its next up. Apple answers every owner inside a share as the caller’s, so right after each start apple’s root exec copies each such secret onto a tmpfs inside the container with that owner and mode and binds it over its place, and the entry’s first process waits for it; a new value reaches it at the next start. |
Service keys
Section titled “Service keys”| Key | Verdict | What SHC does | Code |
|---|---|---|---|
annotations | honoured / reinterpreted | Passed to docker and podman as written. Incus: each becomes the instance’s user.<key> config, metadata Incus keeps and shows; a key Incus does not take, or one under user.shc., user.healthcheck., user.label. or user.incus-compose., is dropped with an X200800INCANN line. Apple: each becomes a label; one that names a label the service or the executor already writes is dropped with an X200801APLANN line. Tenant app: a key in a namespace a runtime acts on (run.oci., io.containers., io.podman., org.systemd., io.kubernetes.cri-o.) is dropped with an X200341CMPTRN line, on every runtime. A $ compose would interpolate anywhere in annotations is refused X403369POLRWT in every app, since compose would change the key after SHC read it; write $$ for a literal $. | modules/app/compose_translate.go DropReservedAnnotations, modules/app/policy_read.go, core/executor/incus/translate.go annotationsToConfig, core/executor/apple/project.go translateService |
attach | dropped | SHC attaches no terminal; the render drops it with an X200341CMPTRN line. | modules/app/compose_translate.go TranslateComposeKeys |
blkio_config | honoured | Host-reaching: installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
build | honoured | Context path rewritten for the replica project; the node builds. | core/pod/project.go files |
cap_add | honoured | A capability outside the runtime’s default set installs only for the master tenant or a deployment granted caps (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> caps), else refused X403990HSTGNT before any pull; app.yaml’s privileges.waivers declares it and admits nothing. apple adds capabilities to the entry’s process inside its own VM; a capability it cannot grant is refused. | modules/app/privilege_class_policy.go EnforcePrivilegeClass |
cap_drop | honoured | incus drops each one with raw.lxc lxc.cap.drop, less what cap_add keeps and less the capabilities SHC’s exec helper needs to start the entry as its user (CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID, SETPCAP, SYS_ADMIN, SYS_CHROOT, SYS_PTRACE); the helper takes those out of the bounding set of what it starts, so the process holds docker’s set and cap_drop: [ALL] starts as it does on docker. apple refuses it: its run flag drops capabilities on the VM’s process; this executor adds capabilities and does not drop them. | core/executor/incus/translate_keys.go capDrops, helperCaps |
cgroup | honoured | host is host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
cgroup_parent | honoured | Host-reaching: installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
command | honoured | ||
configs | honoured | Top-level configs must be inline; see above. Docker writes the config into the container. On podman, whose podman-compose reads no configs key, on incus and for a read_only docker service, SHC writes each config as a file beside the deployment with the uid, gid and mode its reference asks for (root and 0444 when it asks for none), and the service takes it as a read-only bind at its target. That holds where the node runs replica projects and where it runs the whole document. Apple takes the same bind and refuses a reference that sets uid, gid or mode, X400085PODPRJ. | core/pod/project.go StageContentConfig, modules/app/podman_document_configs.go |
container_name | reinterpreted | A fixed name collides across deployments and cannot hold for a scaled service, so the render drops it and the service answers to that name on every network it joins. A name that is the service’s own or another service’s, or a service on another’s network, takes no alias. One X200341CMPTRN line says which. | modules/app/compose_translate.go TranslateComposeKeys |
cpu_count, cpu_percent | dropped | Windows only; the render drops them. | modules/app/compose_translate.go TranslateComposeKeys |
cpu_period, cpu_quota, cpu_shares | honoured | Not read by SHC’s quota; uncharged. incus: the quota over its period is limits.cpu.allowance, and cpu_shares is lxc.cgroup2.cpu.weight by runc’s conversion. | core/executor/incus/translate_keys.go |
cpu_rt_period, cpu_rt_runtime | honoured | Host-reaching: installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
cpus | honoured | Not read by SHC’s quota (only deploy.resources is); uncharged. incus: limits.cpu.allowance, unless deploy.resources.limits.cpus sets it. | modules/app/resource_quota.go ApplyResourceQuotas |
cpuset | honoured | incus: limits.cpu; a lone CPU n becomes n-n, since Incus reads a lone number as a count. | |
credential_spec | dropped | Windows only; the render drops it. | modules/app/compose_translate.go TranslateComposeKeys |
depends_on | honoured | Compose orders the deployment document. In replica projects a dependency inside the pod stays; one on another pod moves into the replica record as a start order for the node agent. A service_completed_successfully dependency is met only by a run of the document the dependent’s own spec holds for it, or of one unchanged since, so during an update the dependent waits for the dependency to run again. When an update changes both, the rollout moves the dependent only after the dependency has run, and the dependent serves its old version until then. | core/pod/project.go dependsOn, modules/pods/sight.go after, core/placement/rollout.go held |
deploy | reinterpreted | A closed set; see deploy keys. | modules/app/swarm_vocabulary.go deployKey |
develop | dropped | Only compose watch reads it; the render drops it. | modules/app/compose_translate.go TranslateComposeKeys |
device_cgroup_rules | honoured | Host-reaching: installs only for the master tenant or a deployment granted devices (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> devices), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
devices | honoured | Host-reaching, as is a /dev bind: installs only for the master tenant or a deployment granted devices (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> devices), else refused X403990HSTGNT before any pull. incus: each entry is an Incus device. /dev/dri, or a card or render node of it at its own path, is a gpu device with the render node’s group and mode, and a CDI name is a gpu of that id. Any other character device is unix-char and a block device unix-block, at the container path, with the host node’s owner and mode, as docker gives them. Read-only or write-only permissions, a GPU at a path other than /dev/dri, and a path that is no device on the node are refused X400776INCKEY. | privilege_class_policy.go EnforcePrivilegeClass, core/executor/incus/devices.go translateDevices |
dns | reinterpreted | A service that states no dns and no network_mode gets the node’s resolver addresses, when the node has any. One that states its own keeps it. | modules/app/inject_resolver.go InjectNodeResolver |
dns_opt | honoured | incus: the start hook binds a resolv.conf with these options over the one Incus writes. SHC adds no option of its own. A bare service name such as db-1 resolves because the node’s DNS answers a name with no dot in the asking replica’s own deployment zone, whatever the image’s libc and ndots. On docker the embedded resolver keeps its own ndots:0 and forwards a single-label name it does not know, so a LAN host only an upstream DNS knows, such as nas, still resolves. An ndots the app states turns that forwarding off on docker, and such a name then needs its full name. | modules/resolver/table.go inOwnZone |
dns_search | honoured | Replica projects append the deployment’s zone. | core/pod/project.go attach |
domainname | honoured | ||
entrypoint | honoured | ||
env_file | honoured | Paths rewritten for the replica project. A file of the app, app/<file>, is read from the copy every node that runs a replica places from the stored app archive, so it reaches a replica on any node. Tenant app: must sit inside the deployment. | core/pod/project.go files, modules/app/package_files.go bindPackageEnvFiles |
environment | honoured | SHC adds OTEL_* when the deployment has an OTel integration, and CA trust variables (plus JAVA_TOOL_OPTIONS on JVM images) on services that dial the estate’s own ACME hosts. On incus a value with a line break reaches the service as written, through the exec helper’s environment file in RAM, never instance config or an argv; a NUL is refused. docker, podman and apple keep a container’s environment in their state on disk, so there every entry with a value is staged in RAM too, bound read-only at /.shc-env, and never handed to the engine: the service starts as root through the exec helper, which sets it and becomes the service’s user, and its health check and every exec run through the helper. An entry with no value, or one that still interpolates a variable, stays with the engine. A reboot stages the file again from the deployment’s document before the node agent starts the container. | inject_otel.go, inject_ca_trust.go, jvm_ca_trust.go, core/executor/entry_env.go |
expose | honoured | The declaration. An exposed port is reachable inside the tenant and is what --expose maps. A service with no declared port is private to its deployment. | modules/app/port_mappings.go |
extends | reinterpreted / refused | Inside the file: the render writes the service out as compose merges it, the base first and the service’s own keys over it; depends_on, links and volumes_from are not inherited. From another file: a module’s is merged at render by compose’s loader; a tenant app’s or an adapter import’s is refused X400126CMPNRM. | modules/app/compose_translate.go TranslateComposeKeys, core/composenorm/loader.go NormalisePackage |
external_links | reinterpreted | A link to a service of the same app is read as links; one to anything outside the app is dropped, since a deployment reaches no other project’s containers by name. | modules/app/compose_translate.go TranslateComposeKeys |
extra_hosts | honoured | The render writes none of its own. | modules/app/fabric_render.go |
gpus | honoured | Host-reaching: installs only for the master tenant or a deployment granted gpus (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> gpus), else refused X403990HSTGNT before any pull. Placement holds the replica to a node whose runtime can pass an NVIDIA GPU (label gpu=nvidia). incus and podman: a CDI device nvidia.com/gpu=<id> of each GPU it names. | privilege_class_policy.go EnforcePrivilegeClass, core/composegpu/gpu.go TakeNvidiaGPUs |
group_add | honoured | Every runtime gives a process docker’s supplementary groups: its user’s own group first, then every group /etc/group lists a user named without a group in, then group_add. incus and podman: SHC’s exec helper starts the process as root and sets them as it becomes the user, reading names in the container’s /etc/group as docker does. incus also reads each name in the image’s /etc/group before the first start and refuses one it lacks X400776INCKEY. podman: a service that drops CAP_SETUID, CAP_SETGID or ALL keeps them in its container for the helper alone, which bounds the command to docker’s set after setting the groups (SHC-3654). | core/executor/incus/execenv/user.go ResolveUser, core/executor/incus/user.go applyGroups |
healthcheck | honoured | A CMD or CMD-SHELL test is run by the runtime. An SHC-HTTP or SHC-TCP test is run by the node, and the runtime gets disable: true (Health probes). | |
hostname | honoured | Yours is kept. Podman: a service that states none and has a network namespace of its own gets its replica entry name (web-r0) as hostname. Podman gives an exec HOSTNAME only when a hostname was stated at create, and docker always sets it, so without one a healthcheck or job reading $HOSTNAME reads nothing there. | core/pod/project.go |
image | honoured | ||
init | honoured | ||
ipc | honoured | service:x makes both one pod, and the replica’s project starts x with ipc: shareable when x states no ipc of its own: docker gives a container a private IPC namespace and lets no second container into one. An x that states private or none is refused X400085PODPRJ, naming both services. Podman: podman-compose 1.6.0 reads no ipc key, so any ipc but private or shareable is refused X400797EXEPDM, naming the service, its ipc and the service it would join. The render records it, placement keeps the pod off podman nodes, and a pod finished for one fails the render X400087PODRTM before anything starts. host and container: are host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. | core/pod/pod.go Group, core/pod/project.go shareIPC, core/executor/podman_refuse.go Refuse |
isolation | dropped | Windows only; the render drops it. | modules/app/compose_translate.go TranslateComposeKeys |
labels | reinterpreted | SHC stamps shc.tenant, shc.stack, shc.environment, shc.service and an empty shc.node and shc.job, overwriting yours. An authored shc.* label is refused X400357LBLSHC and an authored traefik.* label is refused X400358LBLTRF on every app, modules included (a tenant app is also refused X403996TNTCMP). Routes come from --expose. Replica projects add shc.pod, shc.ordinal, shc.location and group labels. A list entry whose key holds $ is refused X400126CMPNRM. | inject_labels.go InjectSHCLabels, package_trust_compose.go RefuseAuthoredShcLabels RefuseAuthoredTraefikLabels, replica_projects.go RefuseUnlabelled |
label_file | reinterpreted / refused | Module: compose’s loader reads the file into the service’s labels at render, with no interpolation, and the label rules above then judge each one as a written label. Tenant app or adapter import: a path that leaves the package, a symlink out of it included, or a file that is not there is refused X400144LBLFIL, naming the service and the path; otherwise the render reads the file inside the package with compose’s parser and writes its labels into the service, whose own labels win, with an X200341CMPTRN line, and the label rules then judge them. | core/composenorm/loader.go NormalisePackage, modules/app/compose_label_file.go InlineLabelFiles |
links | reinterpreted | The render drops the key; the linked service answers to the alias after the colon on its networks, and the linking service starts after it. | modules/app/compose_translate.go TranslateComposeKeys |
logging | reinterpreted | The render drops yours: SHC collects every container’s logs itself. SHC then adds a bounded json-file block (max-size: 50m, max-file: "3") on docker and podman, the runtimes driven through the compose CLI; a replica on incus or apple gets none. | modules/app/compose_translate.go TranslateComposeKeys, modules/app/inject_logging.go InjectLogRotation |
mac_address | honoured | incus: the hwaddr of the NIC of the attachment docker gives it, the fabric’s routed NIC when there is one. | |
mem_limit, mem_reservation, memswap_limit, mem_swappiness | honoured | Not read by SHC’s quota; uncharged. incus: limits.memory (unless deploy.resources.limits.memory sets it), lxc.cgroup2.memory.low, and lxc.cgroup2.memory.swap.max for the swap above the limit. incus refuses mem_swappiness X400776INCKEY: cgroup v2 has no per-container swappiness. | |
models | honoured | ||
network_mode | honoured | service:x makes both one pod. host and container: are host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. Tenant app: otherwise only none or service:. A host service gets no service VIP, so an install never waits on one, and its name answers the underlay address of each node a ready replica of it runs on. A none or container:<x> service gets no VIP either and its name answers nothing, and an --expose route or publish that names one is refused X400242PODADR; a container:<x> service shares x’s network namespace, so on docker and podman, when x is a service of the deployment, it answers at x’s VIP: to the deployment’s own services on every port, to the tenant’s other deployments on the ports x declares. incus runs a none service with no NIC but its own loopback, as docker does, and refuses container: (RX-10); apple refuses every network_mode. | core/pod/pod.go Group, modules/vip/host_network.go |
networks | reinterpreted | Off the shc fabric SHC adds the alias <env>.<service>.<stack> to every network entry and joins provider networks for integrations; on the fabric the node resolver answers that name and no service keeps it as an alias, and the service joins a fabric bridge with a pinned address. Either way SHC declares any network you join but did not declare as external. | install_runner.go serviceNameAliases, AutoDeclareNetworks, fabric_render.go ApplyFabricTarget |
oom_kill_disable, oom_score_adj | honoured | Host-reaching: installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
pid | honoured | service:x makes both one pod. Podman: podman-compose hands pid to podman as written and podman has no service: mode, so a service:x join is refused X400797EXEPDM, naming the service and its pid; placement keeps the pod off podman nodes and a pod finished for one fails the render X400087PODRTM. host and container: are host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. | core/pod/pod.go Group, core/executor/podman_refuse.go Refuse |
pids_limit | honoured | incus: limits.processes, unless deploy.resources.limits.pids sets it. | |
platform | honoured | ||
ports | reinterpreted | Each entry becomes the container port it names, under expose:. A host side is not published and draws warning X200941SWMXLT; an entry with no container port is refused X400941SWMVOC. A canonical system stack keeps its ports: through that translation. On a cluster whose fabric mode is shc and whose fabric range does not overlap the service VIP range, the later render takes every ports: entry out: an app publishes nothing until --expose, and the system ingress’s own publishes become listen rules. Elsewhere, a deployment’s --expose of an outside port renders a long-form ports: entry (mode: host). See Published ports. | swarm_vocabulary.go ports, port_mappings.go ResolveAndInjectPorts |
post_start | honoured / reinterpreted | Docker compose and incus-compose run it. Apple and podman run no hook, so SHC runs each entry in the container once the up has started it, a privileged one as root, and the up logs X200803EXEHOK naming the services; one that fails stops the container and fails the up X500804EXEPOS, as the compose spec says, and the install ends on it at once. Tenant app: a privileged entry installs only for the master tenant or a deployment granted privileged, else refused X403990HSTGNT before any pull; a $ compose would interpolate in an entry’s privileged is refused X403369POLRWT in every app. | core/executor/prestop.go, privilege_class_policy.go EnforcePrivilegeClass |
pre_start | honoured / reinterpreted | Docker compose and incus-compose run it. Apple and podman run no hook, so SHC writes each hook as a one-shot service of the same replica, beside its volumes and namespaces: the service’s spec with the hook’s keys over it, run once, out of the replica’s members, counts and health, on apple the service waiting for it with service_completed_successfully and each hook for the one before. podman’s compose reads no exit code there and starts every container at each up, so on podman SHC ups each hook in turn and the service only once every hook ended 0; a hook that ended non-zero fails the up X500805EXEPRS before the service starts, and the install ends on it at once. Tenant app: refused, see below. | core/executor/prestart.go |
pre_stop | honoured / reinterpreted | Docker: compose runs it on a stop, and SHC runs it from the container’s label before a down, which goes round compose. Incus, apple and podman, whose own tools run no hook: the container keeps its hooks as a label and SHC runs each in it before every stop, a down and an update’s recreate included, a privileged entry as root, and the up logs X200803EXEHOK naming the services; a hook that fails, or that outlasts the stop’s grace, is logged X200802EXEPST and the stop goes on. The compose spec would abort the stop instead; SHC stops a container to drain a node, follow a lost lease or take a deployment down, and no hook may keep it running then. Tenant app: a privileged entry installs only for the master tenant or a deployment granted privileged, else refused X403990HSTGNT before any pull; a $ compose would interpolate in an entry’s privileged is refused X403369POLRWT in every app. | core/executor/prestop.go, privilege_class_policy.go EnforcePrivilegeClass |
privileged | honoured | true installs only for the master tenant or a deployment granted privileged (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> privileged), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
profiles | reinterpreted | Select profiles with --profile on shc install and shc update (--profile debug,tools, or repeated). A service runs when it names no profile or one you selected, as docker compose --profile runs it, and every service loses the key. The selection is kept with the deployment: an update without --profile keeps it, --profile '' runs none, and a backup carries it so a recovery runs the same services. A service that runs but depends on one that does not is refused X400143PRFDEP, naming the profile, as compose refuses it. | modules/app/compose_translate.go TranslateComposeKeysFor |
provider | honoured | ||
pull_policy | honoured | Docker and podman: compose’s own. Incus: missing and if_not_present pull an image only when the node lacks it; always on a tag pulls at every up, and refresh, daily, weekly and every_<duration> pull again once SHC’s own pull of the image on the node is that old; a new image recreates the instance (X200806EXEPRC when SHC cannot record the pull); any other policy is dropped with X200799INCPPL. Apple: always pulls when the entry is about to run; refresh, daily, weekly and every_<duration> pull again as on Incus, and a new image recreates the entry; never and build are refused. | core/executor/pullrefresh.go |
pull_refresh_after | honoured / reinterpreted | Read with pull_policy: refresh. Docker and podman: compose’s own. Incus and apple: as pull_policy above. | core/executor/pullrefresh.go |
read_only | honoured | incus runs the exec helper as the entry’s start hook, which remounts its root read-only before its first process; volumes, tmpfs mounts and /dev/shm stay writable. | core/executor/incus/execenv/starthook.go |
restart | reinterpreted | Rendered restart: "no". Your policy (or deploy.restart_policy.condition) is recorded as labels and x-shc-restart, and the node agent applies it. No policy means on-failure, as compose restarts nothing by default: a clean exit the service makes on its own is its completion and reads degraded, since only no or on-failure says a service runs to completion, a failure is restarted, and a long-running service the node’s shutdown stopped comes back at the next boot (the label shc.restart.defaulted marks it). A service that runs once may also state no itself; run-once work for the whole deployment is a start job (Lifecycle hooks). Both spellings disagreeing draws X200932RSTDIA. | modules/app/restart_default.go RenderRestart |
runtime | honoured | The OCI runtime (e.g. nvidia), not SHC’s runtime. Anything but runc is host-reaching: nvidia needs gpus, any other kernel; each installs only for the master tenant or a deployment granted <class> (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> <class>), else refused X403990HSTGNT before any pull. incus: nvidia is a gpu device of each GPU NVIDIA_VISIBLE_DEVICES names, by its CDI name nvidia.com/gpu=<id>, every GPU when it names none and none for none or void; runc is Incus’s own; any other runtime is refused X400776INCKEY. | privilege_class_policy.go EnforcePrivilegeClass, core/executor/incus/devices.go translateRuntime |
scale | reinterpreted | Read as the replica count, like deploy.replicas; the two disagreeing is refused X400083PODSCL. Removed from replica entries. | core/pod/scale.go authored |
secrets | honoured | Top-level secrets must be vault references; see above. incus binds each one read-only from the file the render staged in RAM, at /run/secrets/<name> or its target. apple shares a service’s own secrets as one read-only directory at /run/secrets, linked from those files, and refuses a target outside it. The value never reaches the disk. | core/executor/incus/translate.go bindSecrets, core/executor/apple/secrets.go readySecrets |
security_opt | honoured | An entry that switches off seccomp, AppArmor, SELinux labels or systempaths installs only for the master tenant or a deployment granted confinement (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> confinement), else refused X403990HSTGNT before any pull. Tenant app: otherwise only no-new-privileges. | privilege_class_policy.go |
shm_size, stop_grace_period, stop_signal | honoured | ||
stdin_open | dropped | SHC attaches no terminal; the render drops it. | modules/app/compose_translate.go TranslateComposeKeys |
storage_opt | honoured | Host-reaching: installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
sysctls | honoured | A namespaced sysctl (net.*, kernel.shm*, kernel.msg*, kernel.sem, fs.mqueue.*) needs no grant. Any other installs only for the master tenant or a deployment granted kernel (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> kernel), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
tmpfs | honoured | On incus every tmpfs reaches incus-compose as a long-form volume with its size in bytes, since incus-compose reads no options from a short-form entry and mounts it whole at 32 KiB. A mount with no size gets what docker gives it, half the node’s RAM or the service’s memory limit when that is smaller, and the up says the size in one line. Incus’s tmpfs device carries a size only, so a mode, uid or gid is dropped, the mount is root’s with mode 1777, and the up says so. | core/executor/incus/tmpfs_size.go |
tty | honoured | ||
ulimits | honoured | apple applies limits to the entry’s process inside its own VM; a limit it cannot apply is refused. | |
use_api_socket | honoured | Host-reaching: installs only for the master tenant or a deployment granted socket (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> socket), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
user | honoured | ||
userns_mode | honoured | host is host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. Tenant app: otherwise only an empty value. | |
uts | honoured | host is host-reaching: installs only for the master tenant or a deployment granted host-namespaces (shc config set privilege.deployment_grants.<tenant>.<environment>.<deployment> host-namespaces), else refused X403990HSTGNT before any pull. | privilege_class_policy.go EnforcePrivilegeClass |
volumes | reinterpreted | See Volumes. | |
volumes_from | reinterpreted / refused | Another service of the app: the render mounts that service’s volumes in this one, read-only for :ro, at every target it does not mount already. container:<name> is refused in every app, the catalog’s too (X403293VOLFRM, naming the service): another container’s volumes are in no backup. | modules/app/compose_translate.go TranslateComposeKeys, modules/app/volumes_from.go |
working_dir | honoured | ||
x-shc-* | read | See x-shc directives. | modules/app/extension_lint.go |
any other x-* | honoured | Compose ignores it. Tenant app: x-podman* and podman-compose’s own service keys (publishall, init-path, pod, name, num, service_name, http_proxy, a mount’s _vol or glob) are refused X403996TNTCMP. | core/executor/extensions.go reads |
Tenant app. On top of the rows above, a tenant’s own app may not write these service keys at all (modules/app/package_trust_compose.go tenantServiceKeys, X403996TNTCMP): build, models, pre_start, provider. It may not interpolate a $VAR the daemon’s environment sets, nor interpolate any field the gate judges. A host-reaching key is not refused here: it is the grant’s, per class, for every app alike. A deployment whose tenant holds the grant true skips this gate.
Logging keys
Section titled “Logging keys”| Key | Verdict | What SHC does |
|---|---|---|
driver | honoured | A tenant app may use json-file, local or none. |
options | honoured | A tenant app may set compress, max-buffer-size, max-file, max-size and mode. |
Restart behaviour
Section titled “Restart behaviour”The node agent on the replica’s node decides whether a container that ended starts again, by the policy the render recorded (modules/nodeagent/supervisor.go). A restart waits a backoff first: 100 ms, doubling up to a minute, back to 100 ms once a restart has stayed up 10 seconds. deploy.restart_policy can set the first wait (delay), the stay-up time (window) and a cap on restarts (max_attempts). always behaves as unless-stopped.
| What ended it | No restart: key | unless-stopped | on-failure | no |
|---|---|---|---|---|
| The process exits 0 | Completed: stays down, reads degraded | Started again | Stays down, reads complete | Stays down, reads complete |
| The process exits non-zero | Started again | Started again | Started again | Stays down, reads failed |
A kill through the engine’s API (docker kill, podman kill) | Started again after the first backoff | Started again after the first backoff | Started again, unless the kill’s signal ended it with 0 | Stays down |
| An OOM kill | Started again | Started again | Started again | Stays down |
A stop (docker stop, podman stop, shc stop) | Stays down until started | Stays down until started | Stays down until started | Stays down |
| The node reboots | Started again at boot, unless it had completed | Started again at boot | Started again at boot, unless the shutdown ended it with 0 | Stays down |
A kill is a crash, whatever its signal. A stop is what the engine reports as one: docker stop sends its stop signal as a kill and reports the stop after the death, and that stop is what keeps the container down. shc stop holds even when it ends in a kill (shc stop --force), because the deployment’s desired state is stopped. A kill made while shcd was not running reads as a stop, since the engine records both alike. A single writer stopped by the lease-loss fence starts again only once its node holds the lease.
deploy keys
Section titled “deploy keys”deploy: is judged as a closed set, so a key outside that set that compose would ignore is refused by name instead (modules/app/swarm_vocabulary.go deployKey). Every refusal here is X400941SWMVOC; every translation logs X200941SWMXLT naming the native form.
| Key | Verdict | What SHC does |
|---|---|---|
mode | honoured / reinterpreted / refused | replicated and global are kept. Global services get a project for each held binding and each eligible ready node with room (global_replicas.go). replicated-job loses its mode and keeps its replicas, global-job becomes global, and each replica runs to one clean exit under restart: on-failure, or restart: "no" when restart_policy.condition is none; the service’s own restart: gives way, as Swarm ignores it. A global job runs once on every eligible node, a node that joins later included. Swarm runs a job again at every deploy; an update here runs a replica again only when its service changed, or a higher count added it. Any other mode is refused. |
replicas | reinterpreted | The replica count, with scale. --scale overrides it (deploy_overrides.go ApplyDeployOverrides); a count above x-shc-scale.max is refused X400902SCLMAX. Removed from replica entries. |
endpoint_mode | honoured / refused | dnsrr is kept. vip is refused. A service virtual IP is a separate mechanism on the shc fabric; this key does not enable it. |
resources.limits.cpus, .memory | reinterpreted | Read as the quota when nothing higher sets one. The container is capped at quota x deploy.limit_ratio, which is 1.5 by default: at the default, a container runs with 1.5x the limit you write here, so cpus: "2.0" runs with a 3.0 CPU cap and memory: 512M with 768M. That rendered cap is what every runtime enforces (docker/podman cpu.max, incus limits.cpu.allowance) and what a job sizing itself from its cgroup reads. shc config set deploy.limit_ratio 1 makes the cap the figure you write. |
resources.limits.pids | honoured | |
resources.reservations.cpus, .memory | reinterpreted | Kept when you write them (lowered to the quota if above it, X200947QTACLM); otherwise derived as quota x deploy.reservation_ratio (1.0), at the ratio of the node the replica lands on. Read as what the replica reserves on its node. On incus, memory is the instance’s lxc.cgroup2.memory.low, as docker’s memory reservation is. |
resources.reservations.devices | honoured / refused | An NVIDIA GPU (capabilities: [gpu], driver nvidia or none) is kept: placement holds the replica to a node whose runtime can pass one (label gpu=nvidia), and incus and podman get it as the CDI device nvidia.com/gpu=<id>. Host-reaching: it needs the gpus grant, as gpus does. Any other device is refused: placement cannot fence it. |
resources.limits.devices, resources.*.generic_resources | refused | No fence for them. |
any other resources key | refused | |
restart_policy.condition | reinterpreted | Folded into restart:, which the node agent applies. |
restart_policy.delay, .max_attempts, .window | honoured / refused | Recorded on the container for the node agent (restart_default.go RestartStanzas). delay is the first wait before a restart, doubling from there up to a minute, where Swarm waits the same delay each time. window is how long a restart must stay up before the count and the wait start over (10 seconds unset). max_attempts is how many restarts the agent makes before the container stays down, 0 for no cap. A delay or window that is not a duration such as 5s, or a max_attempts below 0, is refused. |
placement.constraints | reinterpreted / refused | node.hostname==x and node.labels.k==v (and !=) become the deployment’s --where term. node.role and anything else are refused. |
placement.preferences | dropped | spread: node.labels.* is dropped with a warning: the engine spreads replicas itself. Anything else is refused. |
placement.max_replicas_per_node | refused | No native form. |
labels | reinterpreted | Moved onto the service’s own labels; a label the service already sets keeps its value. |
update_config, rollback_config | honoured | Validated: a key compose does not define, a bad value, or order: start-first on a single writer is refused X400725UPDCFG. Stored in the service spec and read by SHC’s rollout (spec_services.go ServiceRollouts, shc modules/rollout/adapters.go). |
| any other key | refused | No SHC interpretation. |
Volumes
Section titled “Volumes”The short form is the one the mount policy reads. A long-form entry is rewritten to the short string that says the same thing, or refused (core/composenorm VolumeEntry). After that every mount is classified by its source (core/volume/resolve.go DetectMountType):
| Source | Kind | What SHC does |
|---|---|---|
a name (pgdata) | data | Becomes a bind of <deployment dir>/mounts/pgdata, or of a provisioned block volume’s mountpoint when the node has a volume provider and the volume is durable (x-shc-volumes, or kept by backup.yaml). The top-level declaration, with any driver, driver_opts, name, labels or external, is removed. The source is one directory name: data/uploads is refused X403334VOLNST, by shc validate as by the install. While its directory is new or empty, it is seeded with what the image holds at its path, as a compose named volume is; noinit or nocopy leaves it empty. |
./path or a file in the app | file | Bound from the deployment’s copy of the app’s files. The app directory must hold the path: an install or update whose compose binds one it does not hold is refused X400302BNDSRC before anything is changed, since the engine would make an empty directory there. A directory is bound read-only: without :ro it is refused X403335VOLFRO. A single file may be bound writable. |
tmp…/temp…, or a /tmp target | runtime | Bound from a per-deployment runtime directory. The source is one directory name, as a data source is. |
| an absolute path | system | Refused X403322VOLSMT, except /etc/localtime, /etc/timezone, /dev/urandom, /dev/random. The Docker socket mounts the deployment’s own broker socket, never the host’s, and needs the privileged grant (X403983PRVGNT) and a node whose runtime brokers containers, any but apple (X403332CBRRTM); The Docker socket has the rest. /etc/shc/<name> is a platform mount, read-only. |
The short form also carries SHC’s own fields: src:tgt:mode:perm:uid:gid, where mode takes compose’s tokens plus noinit, perm is octal and uid:gid an owner. SHC applies them with a prep step and strips them before compose sees the string (core/volume/parse.go ParseMount). The prep runs on the replica’s node before it starts, while the directory is new or empty, and sets the directory itself, not what is inside it (core/volume/prep.go ApplyPrep). A restore sets the whole restored tree, when the mount names a perm and both owner fields as numbers (modules/backup reapplyMountPrepFromCompose). Give every mount of a shared volume the same fields: the first replica to find the directory empty applies its own. These fields are how a package hands a volume to a non-root uid, so a start job that only runs chown or chmod on one is refused by the catalogue’s tests.
A $ or NUL in a mount string is refused X403323VOLESC: compose would rewrite it after the policy judged it. Put the value in a Jinja var instead.
No mount of a deployment sits inside another mount one of its containers can write (core/volume/nested_source.go). An engine reads a bind’s source again each time the container starts, so a container that could rename data/uploads from inside data would decide what the next start binds there. Give each directory its own name (uploads:/app/uploads), and bind a directory of the app’s files with :ro. Hooks, jobs, exporters and backup converters are held to the same rule.
Long-form mounts
Section titled “Long-form mounts”A long-form volumes: entry is rewritten to the short string that says the same thing, or refused X400126CMPNRM (core/composenorm/composenorm.go VolumeEntry). Tenant app: a long-form bind is refused outright.
| Key | Verdict | What SHC does |
|---|---|---|
type: bind, type: volume | reinterpreted | Rewritten to source:target[:options]. A bind source that does not start with ., / or ~ gets ./. |
type: tmpfs | honoured | Stays long: it has no host side to judge. A source on it is refused. |
type: image, type: npipe, type: cluster | refused | No short form. An entry with no type is refused too. |
source, target | reinterpreted | Strings. target must be absolute; a $, backslash or NUL in either is refused. |
read_only | reinterpreted | true becomes ro. |
bind.propagation | reinterpreted | One of rprivate, private, rshared, shared, rslave, slave. |
bind.selinux | reinterpreted | z or Z only. |
bind.create_host_path | reinterpreted / refused | true is what the short form does already; false is refused. |
volume.nocopy | reinterpreted | true becomes nocopy, and the volume is not seeded from the image. |
tmpfs.size, tmpfs.mode | honoured | Kept on the long entry. |
volume.subpath, bind.recursive, consistency, volume.labels, image | refused | No short form. So is any other key. apple refuses an image key and volume.labels by name. |
Volume declarations
Section titled “Volume declarations”The render removes these when the named volume becomes a bind. Nothing warns. A tenant app may write only driver and labels.
| Key | Verdict | What SHC does |
|---|---|---|
driver | dropped | Removed with the declaration. Tenant app: local only. apple keeps local. |
driver_opts | dropped | Removed with the declaration. Tenant app: refused. apple refuses it. |
name | dropped | Removed with the declaration. Tenant app: refused. apple refuses a name on a volume it creates and keeps one on an external volume. |
labels | dropped | Removed with the declaration. |
external | dropped | Removed with the declaration. Tenant app: refused. apple joins an external volume as named. |
Long-form ports
Section titled “Long-form ports”Off the shc fabric, a deployment’s --expose writes a long-form ports: entry, and apple accepts these keys on it. On that fabric the render writes no ports: entry. See Published ports.
| Key | Verdict | What SHC does |
|---|---|---|
target, published, host_ip, protocol, mode, name | honoured | Off the shc fabric the render’s own publish is mode: host. On that fabric it writes no ports: entry. An app’s authored ports: is rewritten to expose: before this, except a canonical module, whose ports: the later listen-rules render removes. |
app_protocol | honoured | proxy-v2 says the container port reads a PROXY v2 header before its own protocol. The render takes that entry out and declares nothing for it, so no runtime sees it and the tenant cannot reach the port. Only a --expose <port>@<conn>=<service>:<container> on a connection that sends the header (a pfsense connection with proxy_protocol=v2) publishes it, and the port listens only on nodes holding a replica. A plain publish is refused X400986PRXPLN, a connection that sends no header X400986PRXNOH. The app reads the sources it may trust from shc.proxy_protocol_trusted_ips (SHC-3444), and the node listens for the port only from those sources (SHC-3482), which never hold a tenant’s network or a node’s address (FZ-10142). Any other value is passed through. |
Env files
Section titled “Env files”| Key | Verdict | What SHC does |
|---|---|---|
path, required, format | honoured | A long-form env_file entry. apple reads raw or dotenv. |
Depends on
Section titled “Depends on”| Key | Verdict | What SHC does |
|---|---|---|
condition, required, restart | honoured | A long-form depends_on entry. |
Distinct copies of a service are a group, written with {% members %}. See Groups.
A replica whose durable volume sits on its node’s own disk is pinned to that node: placement keeps it there (core/placement/place.go volumeHolds) and a lost node’s replica waits for the node to return (core/placement/movability.go mountMovability). A volume backup.yaml calls scratch does not hold it. See the resource model.
Networks
Section titled “Networks”| Where | Key | Verdict | What SHC does |
|---|---|---|---|
| top level | driver: overlay | dropped | Removed with a warning: a deployment network rides the fabric. |
| top level | ipam, driver_opts MTU | refused | X400782DNTIPM on a network a service joins that is not external and uses the bridge (default) driver: the render allocates that network’s subnet and MTU on its node. On any other network they pass. |
| top level | external, name | honoured | An external network is joined as named. |
| top level | anything else | honoured | Tenant app: only attachable, driver (bridge/overlay), enable_ipv4, enable_ipv6, internal, labels. |
| service | aliases | reinterpreted | SHC appends <env>.<service>.<stack>. |
| service | ipv4_address | reinterpreted | On the fabric network SHC writes the pin. |
| service | anything else | honoured | Tenant app: only the keys in tenantServiceNetworkKeys. |
A service that joins no network joins the deployment’s default network. Code: modules/app/deployment_networks.go PinDeploymentNetworks, install_runner.go AutoDeclareNetworks, core/pod/project.go attach.
x-shc directives
Section titled “x-shc directives”x-shc* is SHC’s namespace and fails closed: an unknown key is X400330XSHUNK, a directive at the wrong level X400331XSHLVL, a misspelt field X400332XSHFLD, a value it cannot honour X400333XSHVAL (modules/app/extension_lint.go xshcRegistry). x-shc directives lists every key, the ones an app writes and the ones SHC writes itself, with its fields, its refusals and what the render does with it. Most are kept in the rendered files, and some also become a label or a route.
Groups are not a directive. They are written with the {% members %} block in the template; see Groups.
Runtime extensions
Section titled “Runtime extensions”Keys a runtime reads beyond the compose spec (core/executor/extensions.go reads). Compose itself ignores them. A tenant app is refused X403996TNTCMP.
| Key | Verdict | What SHC does |
|---|---|---|
x-podman | read | podman-compose, wherever it sits. |
x-incus | read | The incus executor. Every other x- key is dropped first. |
x-incus-compose | read | The incus executor, with x-incus. |
_* | read | podman-compose fields on a service, and _vol on a mount. |
http_proxy | read | podman-compose, on a service. |
init-path | read | podman-compose, on a service. |
name | read | podman-compose, on a service. Not the top-level name. |
num | read | podman-compose, on a service. |
pod | read | podman-compose, on a service. |
publishall | read | podman-compose, on a service. |
service_name | read | podman-compose, on a service. |
build.build_deps | read | podman-compose. |
build.secrets.[].type | read | podman-compose. |
secrets.[].type | read | podman-compose. |
volumes.[]._* | read | podman-compose, the _vol it trusts on a mount. |
volumes.[].glob | read | podman-compose. |
volumes.[].image.propagation | read | podman-compose. |
volumes.[].tmpfs.propagation | read | podman-compose. |
volumes.[].volume.propagation | read | podman-compose. |
volumes.[type=glob].type | read | podman-compose. |
Where the August docs disagree with the code
Section titled “Where the August docs disagree with the code”The code wins. The directives are on one page, x-shc directives, which a test holds to the registry; App definition links it. Routing is --expose, written as a Traefik file route, and an authored traefik.* label is refused X400358LBLTRF on every app. New-line runtime support lists all four runtimes.
Recommended form
Section titled “Recommended form”Write the subset that runs as written, plus the three keys whose rewrite keeps your meaning (restart, named volumes, deploy.resources.limits). Concretely:
- One document, no
include, noextendsfrom another file, no tags. A module that needs them installs through compose’s loader; a tenant’s own app or an adapter’s import that has them is refusedX400126CMPNRM. Alabel_fileinside the package is read into the service’s labels. expose:for every port a service listens on. Neverports:.- Named volumes in short form (
pgdata:/var/lib/postgresql/data); SHC declares them at the top level. Nodriver, no absolute host paths, no$in a mount, no path inside another volume (pgdata/wal), and:roon a directory of the app’s files. deploy.resources.limitswith what the service needs; SHC charges that and derives the rest.restart: unless-stopped(or omit it, same result).healthcheckon every long-running service,depends_onwithcondition: service_healthyon what needs it. An image with no shell or HTTP client gets anSHC-HTTPorSHC-TCPprobe (Health probes).x-shc-scale: {max: 1}on anything with a single writer.- Secrets as
x-shc-vaultreferences, read from/run/secrets/<name>. - No
networks, nolabelsyou need SHC to read, nocontainer_name, nologging.
services: web: image: ghcr.io/example/notes:{{ vars.version | default('2.4.1') }} environment: DATABASE_HOST: db DATABASE_USER: notes DATABASE_PASSWORD_FILE: /run/secrets/db_password REDIS_URL: redis://cache:6379 secrets: - db_password expose: - "8080" volumes: - uploads:/srv/uploads healthcheck: test: ["SHC-HTTP", ":8080/healthz"] interval: 10s timeout: 3s retries: 5 depends_on: db: condition: service_healthy cache: condition: service_started restart: unless-stopped deploy: resources: limits: cpus: "1" memory: 512M x-shc-primary: true
db: image: postgres:16.4 environment: POSTGRES_USER: notes POSTGRES_DB: notes POSTGRES_PASSWORD_FILE: /run/secrets/db_password secrets: - db_password expose: - "5432" volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U notes"] interval: 10s timeout: 3s retries: 5 restart: unless-stopped deploy: resources: limits: cpus: "1" memory: 1G x-shc-scale: max: 1
cache: image: redis:7.4 command: ["redis-server", "--save", "", "--appendonly", "no"] expose: - "6379" restart: unless-stopped deploy: resources: limits: cpus: "0.25" memory: 128M
secrets: db_password: x-shc-vault: ref+vault://db_password?autogenWhat SHC makes of it: the app declares no top-level volumes: or networks:, since the render declares every named volume a service mounts and writes the deployment’s network itself; uploads and pgdata become binds under the deployment’s mounts/ directory on a node with no volume provider, or provisioned block volumes bound from their mountpoints on one that has a provider; each restart: becomes "no" with the policy on labels for the node agent; web runs with a 1.5 CPU, 768M limit and a 1 CPU, 512M reservation, charged as 1 CPU and 512M; every service gets the node resolver, a bounded json-file log on docker and podman, the shc.* labels and the alias <env>.<service>.notes. This is a shape example: supply a real web image before installing it. Refusals still depend on the runtime and cluster state. Install it with --expose notes.example.com to route web; publish nothing.
Ship a backup.yaml beside it, so SHC knows which volumes are durable; with none, every volume is held as kept and shc doctor warns.
Designed, not built
Section titled “Designed, not built”shc.yaml, SHC’s own app file with no compose compatibility: SHC-1361.
What the code does today that this page cannot call a deliberate verdict:
- A declared volume’s
driver,driver_opts,name,labelsandexternalare removed with no warning when the volume becomes a bind. deploy.restart_policy.delay,max_attemptsandwindoware refused by the render, yet the node agent’s label readers (RestartStanzas) read them.cpus,mem_limitand the other service-level resource keys are honoured by the runtime and invisible to the quota.use_api_socketis passed for an app that is not a tenant’s, though the same socket as a bind needs the privilege grant.container_nameon a replicated service,extendsand an aliasedlinksto another pod stop the replica split. The deploy refuses on replica-project nodes and only warns on other nodes.
The page is checked by TestTheComposeKeysPageMatchesTheTable in shc tests/_ce/modules/app/compose_keys_page_test.go. TestARenderPassThatIndexesAnUnlistedComposeKeyFails also checks render readers against the table (SHC-1362, SHC-1385).