Files
k3s/docs/decisions/2026-11-21-traefik-tls-http01.md
hermesandHermes Agent 0f9c5fa105 fix(ingress): isolate HTTP redirect from ACME (#22)
See commit 1af4832. Removes the broken global redirect that exposed internal :8443, pins TLS routes to websecure, and adds a dedicated web redirect middleware so ACME HTTP-01 remains isolated.

---------

Co-authored-by: Hermes Agent <hermes@localhost>
Reviewed-on: org1/infra#22
Reviewed-by: admin <rudolfss13@gmail.com>
Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
2026-11-22 17:49:41 +01:00

3.4 KiB

Decision: TLS termination in Traefik on TCP 443

  • Status: proposed
  • Date: 2026-11-21
  • Scope: K3s edge ingress for public domains

Context

The public HTTP routes are handled by the bundled Traefik instance on xu4 (192.168.1.114). The current public Ingress has HTTP rules for the Hermes, Brencher, Immich, and Gitea hostnames. HTTPS is currently terminated by the KeenDNS/Keenetic path and does not reliably reach the Traefik host rules.

The required target is standard HTTPS with no port suffix:

https://immich.rudolf.keenetic.link/

The same Traefik listener must support SNI/Host-based routing for the other public hostnames.

Decision

Use TCP forwarding from Keenetic to the Traefik node and terminate TLS in Traefik:

WAN TCP 80  -> 192.168.1.114:80
WAN TCP 443 -> 192.168.1.114:443

Configure a Traefik websecure entrypoint on port 443 and use Traefik's Let's Encrypt ACME resolver with the HTTP-01 challenge on the web entrypoint (port 80). Ordinary HTTP routes use a separate permanent redirectScheme middleware on web; TLS routes are pinned to websecure. This keeps the internal ACME challenge router separate from backend routes. Public Kubernetes Ingress resources will opt into TLS using the same resolver.

The router must not terminate TLS, use a KeenDNS HTTPS proxy, rewrite SNI, or replace the HTTP Host header on the forwarded path.

Rationale

  • One standard HTTPS port supports all public domains.
  • Traefik can select the certificate and route by SNI/Host.
  • Certificate issuance and renewal are managed in one place.
  • The design is independent of the Keenetic wildcard certificate.
  • Swarm backends remain behind Traefik and are not exposed directly.

Consequences

  • WAN TCP 80 is a required dependency for every HTTP-01 validation and must reach Traefik directly.
  • ACME storage must be persistent across Traefik restarts and upgrades.
  • A valid email address must be supplied to the ACME resolver configuration.
  • Router-side changes are manual and are not represented by Kubernetes GitOps.
  • The first rollout must be verified at DNS, TCP, ACME, TLS, Ingress, and backend layers separately.

Rejected alternatives

TLS termination on Keenetic

Rejected because it makes the router's TLS proxy the certificate owner and was already observed to return the KeenDNS default 404 instead of reaching the Traefik host route.

One public port per domain

Rejected for the standard URL requirement. It would require URLs such as https://immich.rudolf.keenetic.link:8443/ and would not serve the default port 443.

DNS-01

Not selected because the requested operating model is HTTP-01. DNS-01 can be considered later if direct public port 80 cannot be provided.

Acceptance criteria

  • web listens on TCP 80 and websecure listens on TCP 443.
  • Keenetic forwards TCP 80 and 443 to 192.168.1.114 without TLS termination.
  • The ACME storage is persistent and not committed with credentials.
  • curl -4I http://immich.rudolf.keenetic.link/ returns a permanent redirect to the equivalent https:// URL.
  • HTTP-01 validation succeeds for every hostname requested in the Ingress.
  • curl --resolve <host>:443:<wan-ip> https://<host>/ completes TLS with a certificate valid for <host> and reaches the expected backend.
  • The ACME challenge path remains available on web and does not depend on the KeenDNS web proxy.