## Summary - add the declarative K3s `HelmChartConfig` for Traefik `web`/`websecure` - expose TCP 80/443 and configure the `letsencrypt` HTTP-01 resolver - persist `/data/acme.json` through a PVC - add TLS routing annotations and host lists for the shared public Ingress and Hermes Ingress - document the router cutover, verification procedure, and separate DEC-012 decision ## Scope This PR contains the traffic configuration and documentation. It does not execute `kubectl apply`, change Keenetic, issue certificates, or commit credentials. ## Required operator input before apply - direct WAN TCP 80 and 443 forwarding to 192.168.1.114 - the real Let's Encrypt registration email, inserted through the approved values/secret workflow rather than invented in Git - final review of the installed Traefik chart values and PVC/storage behavior ## Verification - `git diff --check` passed - base: `e084ce4ecf39f19d08ec97fee852f59310e0cdbb` - head: `4f70885` Related decision: `docs/decisions/2026-11-21-traefik-tls-http01.md` --------- Co-authored-by: Hermes Agent <hermes@localhost> Reviewed-on: #21 Reviewed-by: admin <rudolfss13@gmail.com> Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
6.1 KiB
Repository Decisions
This file records repository decisions and the guidance that follows from them. Accepted decisions are in force. Draft decisions are proposals, not policy. Declined decisions are retained for context and are not in force.
Accepted
DEC-001: Make the Kubernetes cluster the primary infrastructure
- Decision: New services should be deployed in the Kubernetes cluster, and services running on other instances should be migrated there. kustomization.yaml is entry point for the Kubernetes cluster configuration.
DEC-002: Document manual operations in README.md
- Decision: The repository's
README.mdshould document useful manual operations and link to all other manual instructions in the repository.
DEC-003: Retire Ansible
- Decision: Ansible is legacy and should be removed strategically.
DEC-004: Treat Docker Swarm files as legacy
- Decision: Docker Swarm files are legacy. New services should not use Docker Swarm and should adopt Kubernetes or other modern orchestration solutions.
DEC-005: Isolate Kubernetes namespaces by default
- Decision: Each namespace should be isolated by default for ingress and egress. Egress should allow only explicitly whitelisted connectivity.
DEC-006: Use GitOps for infrastructure changes
- Decision: Use GitOps as much as possible and keep the repository as the source for infrastructure. Automate changes through CI/CD. Make infrastructure changes through pull requests and have them reviewed before application.
DEC-007: Preserve Docker Swarm deployment for legacy stack files
- Decision: Legacy Docker Swarm stack files should remain compatible with Docker Swarm and be deployed with
docker stack deploy -c <file> <stack-name>, notdocker compose up.
DEC-008: Apply configuration through Git pushes only
- Decision: Configuration should be applied only through Git pushes. Do not apply configuration directly to infrastructure, even when access is available. An agent may apply configs directly tom infrastructure only when explicitly requested.
DEC-009: Use separate NFS state for Kubernetes Hermes
- Context: Kubernetes Hermes must not share mutable state with the legacy Swarm Hermes instance. K3s
local-pathstorage is node-local and does not provide the desired storage layout. - Decision: Kubernetes Hermes uses a static NFS-backed
hermes-data-nfsclaim from192.168.1.96:/root/volumes/hermes/k3s, mounted at/opt/data. The volume uses NFSv3 andRetainreclaim policy. The Swarm directories/root/volumes/hermes/gatewayand/root/volumes/hermes/agentremain separate. - Consequences: The NFS export must allow the current Kubernetes node addresses
100.70.193.97,100.105.201.15, and100.96.92.102, in addition to the existing Swarm LAN allowance192.168.1.0/24. Kubernetes and Swarm Hermes must not use the same mutable state directory concurrently.
DEC-010: Manage web application domains through Keenetic Hero 4G
-
Context: Remote access to web applications in the network is managed through the Keenetic Hero 4G router's web application access settings.
-
Decision: The router-managed web application mappings are:
Domain Remote access Host IP address Protocol TCP port brencher.rudolf.keenetic.linkAuthorized odroid192.168.1.96HTTP 5001immich.rudolf.keenetic.linkPublic odroid192.168.1.96HTTP 2283gitea.rudolf.keenetic.linkNo access odroid192.168.1.96HTTP 3002hermes.rudolf.keenetic.linkPublic xu4_lan192.168.1.114HTTP 80 -
Consequences: These entries describe HTTP/HTTPS web application publishing through the router. They do not imply that arbitrary TCP ports, including Docker API ports
2375or2376, are published. Raw TCP access requires a separate router port-forward or another explicitly configured network path.
Draft
DEC-011: Add authenticated NFS access for Hermes
- Context: The current NFS access model relies on export client allowlists and Unix filesystem permissions. It does not provide NFS username/password authentication.
- Decision: Defer NFS authentication. Do not add Kerberos or store NFS credentials in Kubernetes as part of the current Hermes storage migration.
- Open options: Narrow exports to exact client addresses, replace
no_root_squashwithroot_squashafter validating Hermes UID/GID behavior, or evaluate Kerberos-backed NFS withsec=krb5/sec=krb5pin a separate change. - Status: Draft; the current IP-restricted export model remains in use.
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
80and443directly to192.168.1.114and terminate TLS in Traefik. Use Traefik's Let's Encrypt HTTP-01 resolver on thewebentrypoint and thewebsecureentrypoint on443. Keenetic must not terminate TLS or rewrite SNI/Host. - Consequences: Public port
80is required for certificate issuance and renewal; ordinary HTTP requests are redirected to HTTPS. Traefik ACME storage must be persistent. Router changes remain manual; the operational procedure is documented ink3s_rencher/infrastructure/ingress/README.md. - Status: Proposed; apply only after the router forwarding, ACME email, persistent storage, and live Traefik chart configuration are verified.
Declined
No declined decisions recorded.
Adding a decision
Add each decision under its current status. Use a unique DEC-NNN identifier and include the context, decision, and consequences. Drafts are not instructions; move a decision to Accepted when approved, or to Declined if it is not adopted.
DEC-NNN: Short title
- Context: Why a decision is needed.
- Decision: What is decided.
- Consequences: Important effects or tradeoffs.