forked from org1/infra
docs(ingress): document Traefik TLS and HTTP-01 rollout
This commit is contained in:
@@ -57,6 +57,13 @@ This file records repository decisions and the guidance that follows from them.
|
||||
|
||||
- **Consequences:** These entries describe HTTP/HTTPS web application publishing through the router. They do not imply that arbitrary TCP ports, including Docker API ports `2375` or `2376`, are published. Raw TCP access requires a separate router port-forward or another explicitly configured network path.
|
||||
|
||||
### DEC-012: Terminate public TLS in Traefik
|
||||
|
||||
- **Context:** The public Kubernetes Ingress routes HTTP traffic through Traefik, while the KeenDNS/Keenetic HTTPS path does not reliably preserve the route to the requested host. Standard HTTPS URLs must work for the public domains without per-domain port suffixes.
|
||||
- **Decision:** Forward WAN TCP `80` and `443` directly to `192.168.1.114` and terminate TLS in Traefik. Use Traefik's Let's Encrypt HTTP-01 resolver on the `web` entrypoint and the `websecure` entrypoint on `443`. Keenetic must not terminate TLS or rewrite SNI/Host.
|
||||
- **Consequences:** Public port `80` is required for certificate issuance and renewal. Traefik ACME storage must be persistent. Router changes remain manual; the operational procedure is documented in [`k3s_rencher/infrastructure/ingress/README.md`](k3s_rencher/infrastructure/ingress/README.md).
|
||||
- **Status:** Proposed; apply only after the router forwarding, ACME email, persistent storage, and live Traefik chart configuration are verified.
|
||||
|
||||
## Draft
|
||||
|
||||
### DEC-011: Add authenticated NFS access for Hermes
|
||||
|
||||
@@ -22,6 +22,8 @@ required follow-up actions.
|
||||
- [Gitea runner stack](./poc/gitea/stack-compose.yml)
|
||||
- [Hermes stack](./poc/hermes/README.md)
|
||||
- [Hermes Agent Kubernetes deployment](./k3s_rencher/apps/hermes/README.md)
|
||||
- [Shared Traefik ingress and HTTPS operations](./k3s_rencher/infrastructure/ingress/README.md)
|
||||
- [Traefik TLS/HTTP-01 decision](./docs/decisions/2026-11-21-traefik-tls-http01.md)
|
||||
- [Immich stack](./poc/immich/README.md)
|
||||
- [Lampa stack](./poc/lampa/README.md)
|
||||
- [NetBird deployment](./poc/netbird/README.md)
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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`). 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.
|
||||
- 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.
|
||||
- Existing HTTP routing remains available for the ACME challenge and does not
|
||||
depend on the KeenDNS web proxy.
|
||||
@@ -1,7 +1,7 @@
|
||||
# Shared public ingress
|
||||
|
||||
The common Traefik entrypoint routes public domains to Kubernetes and Swarm
|
||||
backends. The router forwards TCP port `80` to `xu4_lan` (`192.168.1.114`).
|
||||
backends.
|
||||
|
||||
| Domain | Backend |
|
||||
| --- | --- |
|
||||
@@ -13,3 +13,93 @@ backends. The router forwards TCP port `80` to `xu4_lan` (`192.168.1.114`).
|
||||
The Swarm backends are represented by selectorless Kubernetes Services and
|
||||
static Endpoints. The Swarm ports must remain reachable from the Traefik node
|
||||
at `192.168.1.96`.
|
||||
|
||||
## HTTPS target configuration
|
||||
|
||||
The target design is TCP forwarding to Traefik, with TLS termination in
|
||||
Traefik:
|
||||
|
||||
```text
|
||||
WAN TCP 80 -> 192.168.1.114:80
|
||||
WAN TCP 443 -> 192.168.1.114:443
|
||||
```
|
||||
|
||||
Configure the Keenetic entries as raw TCP forwarding. Do not use the KeenDNS
|
||||
HTTPS proxy, terminate TLS on the router, rewrite SNI, or replace the HTTP
|
||||
`Host` header.
|
||||
|
||||
Traefik must provide:
|
||||
|
||||
- `web` on TCP `80` for HTTP and ACME HTTP-01;
|
||||
- `websecure` on TCP `443` for TLS termination;
|
||||
- a persistent ACME storage file, for example `/data/acme.json`;
|
||||
- an ACME resolver with `httpChallenge.entryPoint: web`;
|
||||
- a non-placeholder registration email supplied outside Git.
|
||||
|
||||
The exact `HelmChartConfig` values must match the installed K3s Traefik chart
|
||||
version. Inspect the live `HelmChart/traefik` values before applying a chart
|
||||
override; do not assume that a values schema from another K3s release is
|
||||
compatible.
|
||||
|
||||
For each public Ingress, enable TLS with the same resolver. The resulting
|
||||
Ingress shape is:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
traefik.ingress.kubernetes.io/router.tls: "true"
|
||||
traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- immich.rudolf.keenetic.link
|
||||
```
|
||||
|
||||
With a Traefik ACME resolver, the certificate is stored in the configured
|
||||
persistent ACME storage rather than committed to Git. If the installed chart
|
||||
requires a Kubernetes Secret for a different TLS mode, provision that Secret
|
||||
through the approved secret-management path. Do not commit `acme.json`, a
|
||||
private key, an API token, or an unencrypted Kubernetes Secret.
|
||||
|
||||
## Rollout procedure
|
||||
|
||||
1. Verify that every hostname resolves to the router's current public address.
|
||||
2. Configure Keenetic WAN TCP `80` and `443` forwarding to
|
||||
`192.168.1.114:80` and `192.168.1.114:443`.
|
||||
3. Confirm from an external network that TCP `80` reaches Traefik. The
|
||||
KeenDNS default `404` is not proof of correct forwarding.
|
||||
4. Configure the Traefik `websecure` entrypoint, persistent ACME storage, and
|
||||
HTTP-01 resolver through the repository's GitOps path.
|
||||
5. Add TLS annotations and host entries to the public Ingress resources.
|
||||
6. Apply through Flux only after rendering and reviewing the complete diff.
|
||||
7. Check the Traefik logs and ACME resource/state for the challenge result.
|
||||
8. Test HTTP-01 reachability:
|
||||
|
||||
```sh
|
||||
curl -4v http://immich.rudolf.keenetic.link/.well-known/acme-challenge/test
|
||||
```
|
||||
|
||||
This request must reach Traefik, not the KeenDNS web proxy.
|
||||
|
||||
9. Test TLS and SNI directly against the WAN address:
|
||||
|
||||
```sh
|
||||
curl -4vk \
|
||||
--resolve immich.rudolf.keenetic.link:443:<wan-ip> \
|
||||
https://immich.rudolf.keenetic.link/
|
||||
```
|
||||
|
||||
10. Verify the certificate SAN, the Traefik route, the HTTP status, and the
|
||||
Immich backend separately. Repeat the TLS/SNI test for every public
|
||||
hostname.
|
||||
|
||||
## Failure boundaries
|
||||
|
||||
- DNS resolves incorrectly: fix DNS before changing Kubernetes.
|
||||
- TCP `80` or `443` is refused: fix Keenetic forwarding or WAN reachability.
|
||||
- KeenDNS certificate/default `404` appears: traffic still uses the router
|
||||
proxy instead of TCP forwarding.
|
||||
- ACME challenge fails: inspect port `80`, Host preservation, and Traefik
|
||||
resolver/storage before changing backend routes.
|
||||
- TLS succeeds but the route is `404`/`502`: inspect the Ingress, Service,
|
||||
Endpoints, and Traefik access log separately.
|
||||
|
||||
Reference in New Issue
Block a user