Skip to content
SHC Docs

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.

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.

Execution modeUpstream
Replica projectsThe service’s VIP; no server while the VIP is absent
Deployment project with a fabric pinA ready pin, preferring the local location
Deployment project without a fabric pinThe 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.

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.

--expose requests exposure. A hostname without an outside port requests HTTP(S) ingress; an outside port requests an L4 listener.

Terminal window
shc install nextcloud --expose cloud.example.com
shc install postgres --expose 5432

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