Skip to content
SHC Docs

Network architecture

Layer 9. Fabric. Fabric

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.

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.

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.

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

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.

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 postureCert path
any exposure, a zone-owning DNS-01 connection existsDNS-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 ownerSHC internal-CA leaf (serveSHCLeaf): reachable on the LAN with no public-CA challenge needed
exposure == "internet", LE enabled (leEnabled), no DNS-01 ownerHTTP-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 ownerSHC 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.

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.


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 status and the HUD
  • Health monitoring of specific deployments
  • Metrics collection with labels
  • Log aggregation by tenant or stack

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.