Your own ingress
Everything so far routed plain HTTP to nginx. An app of your own says in
app.yaml what its routes need beyond that, and this page builds one
that needs all of it: a gRPC service behind the hostname, a raw TCP
service on a port of the system Traefik, a service that ends TLS itself
with a certificate SHC hands it, and the exposure the app wants by
default. Four files make the app.
The compose file has four services. grpc is grpcbin, a gRPC test
server that speaks cleartext HTTP/2 on 9000. tls is nginx reading a
certificate from /certs, a bind of the directory where SHC delivers the
material for own.learn.test; it waits for the files before starting,
because they arrive on the first sweep after the install, from the ACME
provider that holds the hostname or from the tenant CA when none does.
echo answers a raw TCP connection on 2222 with one line. client
carries grpcurl.
services: grpc: image: moul/grpcbin:latest expose: - "9000" tls: image: nginx:1.27-alpine command: ["sh", "-c", "while [ ! -s /certs/current/fullchain.pem ]; do sleep 2; done; exec nginx -g 'daemon off;'"] expose: - "8443" volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro - ./site:/usr/share/nginx/html:ro - /etc/shc/tls.serve/own.learn.test:/certs:ro echo: image: alpine:3.20 command: ["sh", "-c", "while true; do echo 'hello over tcp' | nc -l -p 2222; done"] expose: - "2222" client: image: fullstorydev/grpcurl:v1.9.3-alpine entrypoint: ["sleep", "infinity"]server { listen 8443 ssl; server_name own.learn.test; ssl_certificate /certs/current/fullchain.pem; ssl_certificate_key /certs/current/privkey.pem; root /usr/share/nginx/html;}<!doctype html><title>own</title><p>Hello over TLS the app ends itself.</p>app.yaml is the app’s declaration. exposure is the default a
route of this app gets when shc install says nothing, internet here
where the catalogue’s apps mostly say lan. grpc_paths lists the path
prefixes under the hostname that carry gRPC: each gets a second router
that dials the service over cleartext HTTP/2, carries no middleware and
skips the login gate, since a gRPC client brings its own bearer. The
reflection prefixes are there so grpcurl list works. tcp_ingress
names a service that speaks raw TCP and the Traefik entrypoint it wants,
ssh, the one the system Traefik knows how to open. certs is the
reload contract for the certificate SHC delivers: which services to
restart, or what to run in them, when the material rotates.
name: ownversion: "1"description: An app that needs more than an HTTP route.exposure: internetgrpc_paths: - /grpcbin.GRPCBin/ - /hello.HelloService/ - /grpc.reflection.v1.ServerReflection/ - /grpc.reflection.v1alpha.ServerReflection/tcp_ingress: - name: ssh service: echo port: 2222certs: - reload: tls: restartInstall it with the hostname routed to the gRPC service and the TLS service published on a port of its own:
$ shc install ~/learn/own -s own --expose own.learn.test=grpc:9000 --expose 18443=tls:8443 --dns-provider learn-dnsinstalling deployment "own"[own] Healthy 4/4✔ client healthy✔ echo healthy✔ grpc healthy✔ tls healthy✔ installed deployment "own"exposure: internet$ shc status -s own...Published ports...
2 nodes, 1 deployment$ shc ingress ls...The ingress has the HTTP router for own.learn.test with the gate in
front of it and, beside it, one router per gRPC prefix with no GATE at
all. Call the service from the app’s own client, first by name inside
the tenant and then through the ingress. -plaintext is the cleartext
HTTP/2 the server speaks; -insecure accepts the tenant’s own chain at
the edge. list asks the server what it serves, through reflection:
$ shc exec -s own -S client -- grpcurl -plaintext grpc.own.prod.prod.shc.internal:9000 listaddsvc.Addgrpc.gateway.examples.examplepb.ABitOfEverythingServicegrpc.reflection.v1alpha.ServerReflectiongrpcbin.GRPCBinhello.HelloService$ shc exec -s own -S client -- grpcurl -insecure own.learn.test:443 list...$ shc exec -s own -S client -- grpcurl -insecure -d '{"greeting":"shc"}' own.learn.test:443 hello.HelloService/SayHello{ "reply": "hello shc"}The second list went through Traefik on 443, which ended TLS with the
leaf for own.learn.test and dialled grpcbin over HTTP/2; without the
prefixes in app.yaml the same call would meet the login gate and fail.
A raw TCP port on the system Traefik
Section titled “A raw TCP port on the system Traefik”tcp_ingress is one half. The other is the platform’s: the system
Traefik opens its ssh entrypoint on the port you give it and binds it
to exactly one deployment, because a TCP router without TLS cannot tell
two deployments apart. Both are vars of the traefik system app, set
through config and applied by updating it in the master tenant it
lives in; the deployment is named tenant, environment, deployment:
$ shc config set modules.traefik.vars.ssh.port 2222KEY VALUE SCOPEmodules.traefik.vars.ssh.port 2222 global$ shc config set modules.traefik.vars.ssh.deployment prod/prod/ownKEY VALUE SCOPEmodules.traefik.vars.ssh.deployment prod/prod/own global$ shc config ls --prefix modules.traefik.vars.ssh....$ shc -t master update traefik...The system Traefik comes back with the entrypoint and publishes 2222
on every node, and an armed tcp_ingress binding is an ingress route of
the fabric policy, so the grant to dial echo goes with it. Connect to
the port on two nodes. It is every node’s, so the line arrives whichever
of them holds echo’s replica:
$ nc -w 3 127.0.0.1 2222hello over tcp$ nc -w 3 127.0.0.1 2222hello over tcpEach node’s Traefik took the connection on its own 2222 and relayed it
to echo over the fabric. The grant that lets it is the binding’s: the
policy gives the system Traefik that one service on that one port, the
way a routed host gets its backend, and clearing the binding takes the
grant with it. shc cluster fabric explain reads it back. -t master
names the end Traefik runs in, and --target-tenant and
--target-environment the deployment’s:
$ shc -t master cluster fabric explain traefik own:echo --target-tenant prod --target-environment prod --port 2222verdict ACCEPTbecause ingress route: ingress -> prod/prod/own echo/tcp/2222from master/default/traefik/forward-auth 10.128.16.134 on node-b7e0d23b1275to prod/prod/own/echo 10.128.33.7 on node-acd3732ccadbflow tcp/2222steps node-b7e0d23b1275 fabric_egress rule 33 ingress accept ip saddr { 10.128.16.134, 10.128.16.135, 10.128.16.136 } ip daddr 10.128.33.7 tcp dport 2222 accept comment "ingress -> prod/prod/own echo/tcp/2222" node-acd3732ccadb fabric_ingress rule 34 ingress accept ip saddr { 10.128.16.134, 10.128.16.135, 10.128.16.136 } ip daddr 10.128.33.7 tcp dport 2222 accept comment "ingress -> prod/prod/own echo/tcp/2222"kernel node-b7e0d23b1275 sha256:a9ee154f4f9d93dc032474598e4d86ec367c664a08c154a1146bb5832c62c659, in sync with the compiled rulesetThis is how the gitlab app in the catalogue serves git over SSH on a port of the edge.
A service that ends TLS itself
Section titled “A service that ends TLS itself”Traefik ended TLS for the gRPC route. tls ends it itself: the bind of
/etc/shc/tls.serve/own.learn.test gave the container the leaf and key
SHC issued for the hostname, under current, and certs in app.yaml
says what to do when they rotate. The deployment may bind that directory
because it owns the hostname; another deployment binding it is refused at
install. No ACME provider holds this hostname, so the material delivered
is the tenant CA’s leaf, the one Traefik already serves at the edge. Read
the page over the port published for it, then the chain nginx serves:
$ curl -sk --resolve own.learn.test:18443:127.0.0.1 https://own.learn.test:18443/<!doctype html><title>own</title><p>Hello over TLS the app ends itself.</p>$ openssl s_client -connect 127.0.0.1:18443 -servername own.learn.testConnecting to 127.0.0.1depth=1 O=shc, CN=shc-prod-ca-intermediateverify error:num=20:unable to get local issuer certificateverify return:1depth=0 O=shc, CN=own.learn.testverify return:1CONNECTED(00000003)---Certificate chain 0 s:O=shc, CN=own.learn.test i:O=shc, CN=shc-prod-ca-intermediate... 1 s:O=shc, CN=shc-prod-ca-intermediate i:O=shc, CN=shc-global-ca...subject=O=shc, CN=own.learn.testissuer=O=shc, CN=shc-prod-ca-intermediate...The same chain the edge served for site.learn.test on
the TLS page, now served by the app’s own nginx.
shc cert delivery lists each hostname delivered, the node that holds
the material, where it came from, and the class of certificate requested
against the one delivered:
$ shc cert deliveryTENANT HOST NODE SOURCE REQUESTED DELIVERED ISSUER EXPIRES MATCHprod own.learn.test far01 tenant-ca tenant-ca tenant-ca shc-prod-ca-intermediate, shc 2027-01-09 yesThe material for own.learn.test is on the node that runs tls, so its
row names that node whichever node you ask, and SOURCE reads tenant-ca
because no ACME provider holds the hostname. site.learn.test and
www.learn.test, the routes the earlier pages made, have no row: SHC
delivers a hostname’s material only to a deployment that binds it, and
own is the one that does. The cluster keeps own with everything else
this ladder installed.
This is the end of the network ladder. The access ladder takes the login gate from here.