Files
infra/docs/decisions/2026-11-21-traefik-tls-http01.md
hermesandHermes Agent 0d29c7d7af fix(ingress): let Traefik own HTTP-01 challenge path (#23)
## Problem

Let's Encrypt HTTP-01 requests were reaching ordinary Kubernetes HTTP routes instead of Traefik's internal ACME challenge handler. The CA observed backend responses (404/401/403), so Traefik continued serving its default certificate.

## Change

- remove the Kubernetes `web` catch-all redirect Ingress and its backend routes;
- restore Traefik entrypoint HTTP-to-HTTPS redirect;
- set the redirect port explicitly to public `443`, preventing internal `:8443` in `Location`;
- keep `web` available for the built-in HTTP-01 challenge router;
- update the ingress decision/runbook.

## Verification

- `git diff --check` passes;
- `kubectl kustomize k3s_rencher/infrastructure/ingress` renders successfully;
- rendered resources no longer include the Kubernetes HTTP redirect catch-all;
- the Traefik redirect explicitly targets public port `443`.

## Post-merge acceptance

Verify externally that HTTP redirects to `https://<host>/` without `:8443`, a real HTTP-01 attempt succeeds, and the served certificate has Let's Encrypt issuer/SANs for all four domains.

---------

Co-authored-by: Hermes Agent <hermes@localhost>
Reviewed-on: #23
Reviewed-by: admin <rudolfss13@gmail.com>
Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
2026-11-22 22:29:19 +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 requests use a permanent entrypoint redirect to websecure with public port 443; 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.