Traffic across runtimes
Layer 10. Edge. Edge
SHC renders ingress intent into Traefik file-provider routes. The upstream depends on the deployment’s execution mode and fabric addresses.
Request path
Section titled “Request path”flowchart LR C["Client"] --> T["Traefik: TLS and HTTP route"] T --> U["Service VIP or ready fabric pin"] U --> R["App container"]modules/app/ingress_materialize.go reads replicated ingress intent and
writes the local dynamic configuration. The reconcile in
subsystems/impl/ingress_materialize.go runs on every node and reloads the
Traefik replicas on that node. The system Traefik deployment is global, so
every node runs a replica.
Upstream selection
Section titled “Upstream selection”| Execution mode | Upstream |
|---|---|
| Replica projects | The service’s VIP; no server while the VIP is absent |
| Deployment project with a fabric pin | A ready pin, preferring the local location |
| Deployment project without a fabric pin | The local compose container name |
An empty upstream produces an empty server list, which Traefik answers
with HTTP 503. The selection lives in CE
modules/app/ingress_fabric_upstream.go and ingress_vip_upstream.go.
Service VIPs map to ready replica pins through nftables. A remote backend is reached through shc0 on UDP 4243. See Network fabric and the service VIP design.
Runtime boundaries
Section titled “Runtime boundaries”A node runs one runtime: docker, podman, incus or apple. Docker,
Podman and Incus attach to shc0 on Linux, each container a routed /32
from its node’s chunks: on a veth of its own through SHC’s network driver
on Docker and Podman, on a routed NIC on Incus. A Mac node has mesh0, and
holds shc0 chunks with its own key once its pf policy is loaded (SHC-1623,
SHC-1642); each apple replica runs on a vmnet network of its own. Sources:
CE daemon/imports.go, core/hostplat and modules/fabric/types.go.
Linux cluster nodes with the shc fabric and service VIPs, and Mac nodes on
the apple runtime, run replica projects. Each replica runs on the node it
is bound to, which need not be the node that rendered it (SHC-1426). Other
nodes run one deployment project. Runtime support records
these limits.
Published ports
Section titled “Published ports”--expose requests exposure. A hostname without an outside port requests
HTTP(S) ingress; an outside port requests an L4 listener.
shc install nextcloud --expose cloud.example.comshc install postgres --expose 5432On the shc fabric, direct L4 publication uses SHC’s own listen rules on
the selected nodes. The render writes no compose ports: entry for it.
A local ready replica receives the connection when possible; otherwise
the listener forwards it to a ready replica and masquerades the source.
+spread distributes connections across ready replicas.
Listener selectors after @ choose where the port listens. Placement
expressions --where and --prefer choose where a deployment may run.
These are separate decisions. Sources: CE modules/app/publish_listen.go,
published_ports_intent.go and modules/fabric/published.go.