Skip to content
SHC Docs

Render once

Layer 7. Engine. Layer page.

A deployment is rendered once. That render is stored before it names a node. The leader finishes the stored render for a node. The node does not render. It materialises clusterfs from the store and starts replicas from the stored spec.

sequenceDiagram
participant Deploy
participant Store
participant Leader
participant Node
Deploy->>Deploy: render the compose once
Deploy->>Store: store the render before fabric, networks, replica projects
Leader->>Store: finish the stored render for the node
Leader->>Store: store the spec and bind replica rows
Node->>Store: materialise clusterfs
Node->>Node: start replicas from the stored spec
flowchart TD
R["ExecuteCompose: the app render and the injectors that name no node"] --> Q{"replica projects run"}
Q -->|no| W["no stored render; a later move is refused by name"]
Q -->|yes| S["store the render: compose, platform DNS set, group members, scale"]
S --> L{"FinishStoredRender"}
L -->|off the leader| X1["X403144RNDLDR"]
L -->|no stored render| X2["X404143RNDNOF"]
L -->|on the confirmed leader| F["the node's fabric pins and deployment networks, sealed replica documents, bound replica rows"]
F --> N["the node materialises clusterfs and starts replicas from the stored spec"]

ExecuteCompose encodes the stored render after the app render and the injectors that do not name a node, and before the fabric target, the deployment networks, and the replica projects (ce modules/app/install_runner.go). The stored value is the compose, the platform DNS set, the group members, and the scale (ce modules/app/stored_render.go).

FinishStoredRender runs only on the confirmed leader. It reads the stored render from the store, applies that node’s fabric pins and deployment networks, seals the replica documents, and binds the replica rows. It does not read the app and it does not run Jinja. Off the leader it returns X403144RNDLDR. A spec with no stored render returns X404143RNDNOF.

Where replica projects do not run, the deploy stores no render, and a later move is refused by name (ce modules/app/install_runner.go).

A path package is bytes on the node that received the install. That node resolves it, interns it in the cluster’s app archive and hands the install to the leader with the archive digest, and the leader renders the archive (ce modules/app/app_archive.go, daemon/services_install_placement.go, SHC-1722). Nothing holds a path app to the node that typed it. shc update of a path deployment does the same from the node it is typed on, and a node without the directory refuses it there with X404064SRCNFD naming the directory (ce modules/app/update_dispatch.go, SHC-1784).

A vapp instance is placed on the render leader too, from whichever node it is typed on: it reads the host’s manifest and writes its sidecar into the host’s deployment directory, which the leader holds. Its service jobs run in the host’s live container on the node the host’s replica runs on, the route a socket’s service job takes. Its uninstall goes to the leader as well (ce modules/app/router.go, modules/app/vdeployment_runner.go, modules/app/uninstall_dispatch.go, SHC-1724).

Each node builds its own clusterfs from the store and swaps current (ce modules/clusterfs/materialiser.go). The node’s runner starts replicas from the stored spec.

A finish computes values from the daemon as well as from the render: a pinned replica’s host-gateway, the platform paths its binds name. When a newer shcd leads, the leader-only app_refinish loop finishes every committed stored render again with what that shcd computes (ce modules/app/refinish.go, subsystems/impl/refinish.go). It waits until every member with a ready lease runs that build or a newer one, and an older shcd leading in a roll never re-finishes. It also waits until the leader reads what a finish reads: whether its process runs replica projects, and each member’s runtime and fabric address. Their lookups answer empty in the first moments after shcd starts, an empty runtime renders as docker and an empty fabric address leaves host-gateway to the runtime, so a finish then would store a spec the node never ran (ce modules/app/refinish_inputs.go, X503160RFNINP). Steps registered with app.RegisterRefinishPrep run first, in order, and a failed one stops the pass. Two workers re-finish the deployments, each under the deployment’s relocation lease. A finish that matches the stored spec writes nothing. One that differs is stored, and the rollout moves its replicas in batches as it moves an update’s, so a replica whose document did not change moves without a restart; the worker waits for that rollout before it takes the next deployment. What fails is retried alone every minute, and the build is recorded in the cluster’s kv store once nothing is left failing. Doctor’s app.refinish names the members a pass waits for and every deployment or prep still failing, with its code.

Sources: ce modules/app/install_runner.go, modules/app/stored_render.go, modules/app/refinish.go, modules/clusterfs/materialiser.go.