Network architecture
Layer 9. Fabric. Fabric
Network Scopes
Section titled “Network Scopes”The render allocates deployment networks and records them in
networks.json. Each is node-local, a /25 of the deployment range at MTU
1500. On the shc fabric every pinned service also joins the node’s fabric
network shc_fabric with its pin, a routed /32 on a link of its own.
shc0 routes traffic between nodes. Sources: CE
modules/app/deployment_networks.go, modules/depnet/depnet.go and
fabric_render.go.
DNS Resolution
Section titled “DNS Resolution”SHC injects the node resolver into services that declare neither dns:
nor network_mode, when resolver addresses are available. Docker’s
embedded DNS answers its local network names and forwards other names to
shcd. Podman fabric nodes keep engine DNS off the attached networks so
queries reach shcd with the container’s source address.
Provider aliases are recorded in the deployment’s stored spec. The node
resolver answers from current service state; an integration supplies the
provider’s names and credentials. Sources: CE
modules/app/inject_resolver.go, fabric_render.go and
modules/resolver/source.go. See Runtime
support for Podman DNS limits.
Network Attachment
Section titled “Network Attachment”No tenant has a bridge. A pin’s tenant is a label the node’s policy reads. nftables rules allow traffic inside a deployment and open declared service ports inside its tenant. Cross-tenant connections are refused, with explicit exceptions for the system tier’s roles. Network membership alone does not define these permissions.
Linux’s node-plane table restricts container access to control listeners.
See Network fabric for the policy and
Security for its trust boundary. Source: CE
modules/fabric/policy/doc.go.
Traefik Integration
Section titled “Traefik Integration”Ingress is requested per deployment with --expose <hostname> at install time
(repeatable). There is no public_hosts/public_ports field in app.yaml:
hostnames come from the install flags, and the access (--gated/--open)
and exposure (--public) axes decide gating and reachability (see
Access control).
Route generation
Section titled “Route generation”SHC writes app routes as Traefik file-provider documents from replicated ingress intent. Replica projects use a service VIP as the upstream; a deployment project uses a ready fabric pin when it has one, otherwise a local container name. The route has no server while its required upstream is unavailable.
Sources: CE modules/app/ingress_materialize.go,
ingress_fabric_upstream.go and ingress_vip_upstream.go. See
Traffic across runtimes.
TLS Configuration
Section titled “TLS Configuration”The primary TLS path is a per-tenant internal CA leaf-signer, not
Let’s Encrypt. Each tenant has its own two-tier autogen CA: a self-signed
root + an issuing intermediate, minted by MintAutogenCA and stored in
modules/ca/ (modules/ca/ca.go, store.go). When SHC
renders an ingress route it mints a short-lived ECDSA P-256 leaf for the host
(SignLeaf / the leafSigner interface), writes the cert+key into the
dynamic certs/ dir, and adds a tls.certificates block so Traefik’s file
provider serves that leaf (serveSHCLeaf in inject_traefik.go). Traefik
SNI-matches each served leaf to its router. The tenant CA root is also
materialized as a bundle (certs/shc-ca-bundle.pem) so the forward-auth
sidecar trusts the SHC-served leaf.
TLS posture is decided per host (writeIngressRouteFile), with the
leafSigner as the master switch (nil signer ⇒ bare tls: {}):
| Host posture | Cert path |
|---|---|
| any exposure, a zone-owning DNS-01 connection exists | DNS-01 certificate from the daemon’s ACME source (the leader orders it once, through that connection), served from certs/acme-<router>; the SHC leaf until it is issued |
exposure == "lan", no DNS-01 owner | SHC internal-CA leaf (serveSHCLeaf): reachable on the LAN with no public-CA challenge needed |
exposure == "internet", LE enabled (leEnabled), no DNS-01 owner | HTTP-01 certificate from the daemon’s ACME source (every node’s Traefik routes /.well-known/acme-challenge/ to its daemon), served from certs/acme-<router>; the SHC leaf until it is issued |
exposure == "internet", LE disabled, no DNS-01 owner | SHC internal-CA leaf (fallback, stays reachable) |
So DNS-01 serves any host whose zone a DNS-01 connection owns, HTTP-01 is
reserved for internet-exposed hosts that opt into it, and every other host
serves the per-tenant internal-CA leaf. One route file can mix an ACME host (an
issued certs/acme-* pair) with an internal-CA host (bare tls: {} + served
leaf). The websecure entrypoint (port 443) and automatic HTTP→HTTPS
redirect apply across both paths.
DNS Providers (--expose)
Section titled “DNS Providers (--expose)”When deploying with --expose, SHC creates DNS records using the resolved provider
for that deployment scope:
- A for IPv4 targets
- AAAA for IPv6 targets
- CNAME for hostname targets
Traefik is synced on-demand when DNS providers are added, removed, or modified. Only Traefik instances with deployments using affected providers are updated, and each sync writes all current providers to the Traefik instance.
Service Discovery Labels
Section titled “Service Discovery Labels”SHC adds container labels for service discovery:
labels: - "shc.tenant={tenant}" - "shc.stack={stack}" - "shc.environment={environment}" - "shc.node_id={node_id}" - "shc.app={app_name}" - "shc.service={service_name}" - "shc.deployment_id={deployment_id}"These labels enable:
- Scoping by tenant/stack/environment in
shc statusand the HUD - Health monitoring of specific deployments
- Metrics collection with labels
- Log aggregation by tenant or stack
Communication via integrations
Section titled “Communication via integrations”Plugs and sockets supply provider names and connection details. On the
fabric, this wiring does not grant permission: the tenant’s declared-port
policy determines reachability. Sources: CE modules/app/fabric_render.go
and modules/fabric/policy/doc.go.