Traffic Flow¶
Status
Implemented. Exposure through a Gateway API TLSRoute was verified on the E2E cluster with Envoy Gateway (/api/v2/ping), with the frontend as a sidecar. The E2E test also checks that the web pod listens only on ports 8080 and 8443, and the operator registers Smart Proxies through the frontend over HTTPS. LoadBalancer, ClusterIP, and Route are covered by controller tests only. /pub content is target design.
Why a frontend¶
Foreman uses client certificates as part of its protocol. The frontend verifies them with SSLVerifyClient optional and forwards the result as SSL-CLIENT-S-DN, SSL-CLIENT-CERT, and SSL-CLIENT-VERIFY.
Some ingress controllers can verify and forward client certificates. The OpenShift Router does not provide this in the form Foreman expects. A portable design therefore uses TLS passthrough to Apache in the cluster, with one set of path rules on every platform.
Why a sidecar¶
Apache runs as the container httpd in every <foreman>-web pod, next to Puma in the container foreman. Puma binds only to the Unix socket /run/puma/puma.sock in a shared emptyDir and has no TCP listener. Apache proxies to it with unix:/run/puma/puma.sock|http://localhost/. This matches upstream Foreman, which runs Puma behind Apache. Passenger is not an option.
Earlier versions ran Apache as a separate Frontend resource that proxied to Puma on port 3000. Any pod that could reach that port could set the SSL-CLIENT-* headers itself and impersonate a Smart Proxy (#7). Mutual TLS between a separate frontend and Puma was considered and rejected:
- With the sidecar, Puma is not reachable from the network at all. There is no port left to protect.
- No additional certificates, issuers, or rotation for the hop between Apache and Puma.
- The protection does not depend on whether the cluster enforces NetworkPolicy.
The trade-offs:
- Frontend and web scale 1:1 through
spec.web.replicas. The frontend cannot be scaled on its own. - A change to the frontend configuration or its certificates restarts the web pods. Dynflow is not affected.
- During a database migration, the web Deployment is scaled to zero, so the frontend is down as well.
Exposure¶
The Service <foreman>-web exposes the frontend containers on port 443 (HTTPS, container port 8443) and port 80 (HTTP, container port 8080). A Route, TLSRoute, or HTTPRoute is named <foreman> and points to that Service.
spec.frontend.exposure.type |
Result |
|---|---|
Auto |
Route on OpenShift, LoadBalancer elsewhere |
LoadBalancer |
<foreman>-web of type LoadBalancer |
Route |
OpenShift Route with termination: passthrough |
TLSRoute |
Gateway API TLSRoute on tlsSectionName, plus an HTTPRoute for port 80 when httpSectionName is set |
ClusterIP |
<foreman>-web of type ClusterIP only |
What the frontend serves¶
- HTTPS on container port 8443 (Service port 443) for users, the API, and proxies
- HTTP on container port 8080 (Service port 80) for
/unattendedrequests from installers. This virtual host never carries client certificates. /pubcontent, such as the CA certificate (planned)- External authentication, where used (planned)
The Apache configuration is generated by the operator from its own template and stored in the ConfigMap <foreman>-frontend. Both virtual hosts proxy every path to the Puma socket with ProxyPreserveHost. The HTTPS virtual host also allows WebSocket upgrades.
The operator calls the Foreman API over HTTPS at https://<foreman>-web.<namespace>.svc, with spec.fqdn as SNI and Host. It verifies the frontend certificate against ca.crt of the server certificate Secret, or against the system roots when the Secret has no ca.crt.
Trust boundary¶
Foreman trusts the forwarded identity headers. Therefore:
- Only the
httpdcontainer in the same pod reaches Puma, through the socket. - Apache overwrites the
SSL-CLIENT-*headers on every request and removesREMOTE-USER. trusted_proxiesin Foreman lists only loopback (127.0.0.0/8and::1). The client address is theX-Forwarded-Forentry that Apache appends.
Foreman 5.0 rejects undeclared Host headers, so spec.fqdn and spec.aliases must be complete.
Licensing¶
The foremanctl vhost templates are GPL-3.0. The frontend configuration is written independently from the described behavior.