Skip to content
SHC Docs

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.

~/learn/own/compose.yaml
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"]
~/learn/own/nginx.conf
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;
}
~/learn/own/site/index.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.

~/learn/own/app.yaml
name: own
version: "1"
description: An app that needs more than an HTTP route.
exposure: internet
grpc_paths:
- /grpcbin.GRPCBin/
- /hello.HelloService/
- /grpc.reflection.v1.ServerReflection/
- /grpc.reflection.v1alpha.ServerReflection/
tcp_ingress:
- name: ssh
service: echo
port: 2222
certs:
- reload:
tls: restart

Install it with the hostname routed to the gRPC service and the TLS service published on a port of its own:

home01
$ shc install ~/learn/own -s own --expose own.learn.test=grpc:9000 --expose 18443=tls:8443 --dns-provider learn-dns
installing 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:

home01
$ shc exec -s own -S client -- grpcurl -plaintext grpc.own.prod.prod.shc.internal:9000 list
addsvc.Add
grpc.gateway.examples.examplepb.ABitOfEverythingService
grpc.reflection.v1alpha.ServerReflection
grpcbin.GRPCBin
hello.HelloService
home01
$ shc exec -s own -S client -- grpcurl -insecure own.learn.test:443 list
...
home01
$ 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.

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:

home01
$ shc config set modules.traefik.vars.ssh.port 2222
KEY VALUE SCOPE
modules.traefik.vars.ssh.port 2222 global
$ shc config set modules.traefik.vars.ssh.deployment prod/prod/own
KEY VALUE SCOPE
modules.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:

home01
$ nc -w 3 127.0.0.1 2222
hello over tcp
far01
$ nc -w 3 127.0.0.1 2222
hello over tcp

Each 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:

home01
$ shc -t master cluster fabric explain traefik own:echo --target-tenant prod --target-environment prod --port 2222
verdict ACCEPT
because ingress route: ingress -> prod/prod/own echo/tcp/2222
from master/default/traefik/forward-auth 10.128.16.134 on node-b7e0d23b1275
to prod/prod/own/echo 10.128.33.7 on node-acd3732ccadb
flow tcp/2222
steps
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 ruleset

This is how the gitlab app in the catalogue serves git over SSH on a port of the edge.

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:

home01
$ 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>
home01
$ openssl s_client -connect 127.0.0.1:18443 -servername own.learn.test
Connecting to 127.0.0.1
depth=1 O=shc, CN=shc-prod-ca-intermediate
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 O=shc, CN=own.learn.test
verify return:1
CONNECTED(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.test
issuer=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:

home01
$ shc cert delivery
TENANT HOST NODE SOURCE REQUESTED DELIVERED ISSUER EXPIRES MATCH
prod own.learn.test far01 tenant-ca tenant-ca tenant-ca shc-prod-ca-intermediate, shc 2027-01-09 yes

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