Files
k3s/AGENTS.md
T
hermesandHermes Agent 24198a56e4 [in-review] feat(ingress): Traefik TLS on 443 with HTTP-01 (#21)
## 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: org1/infra#21
Reviewed-by: admin <rudolfss13@gmail.com>
Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
2026-11-22 17:31:10 +01:00

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.md should 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>, not docker 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-path storage is node-local and does not provide the desired storage layout.
  • Decision: Kubernetes Hermes uses a static NFS-backed hermes-data-nfs claim from 192.168.1.96:/root/volumes/hermes/k3s, mounted at /opt/data. The volume uses NFSv3 and Retain reclaim policy. The Swarm directories /root/volumes/hermes/gateway and /root/volumes/hermes/agent remain separate.
  • Consequences: The NFS export must allow the current Kubernetes node addresses 100.70.193.97, 100.105.201.15, and 100.96.92.102, in addition to the existing Swarm LAN allowance 192.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.link Authorized odroid 192.168.1.96 HTTP 5001
    immich.rudolf.keenetic.link Public odroid 192.168.1.96 HTTP 2283
    gitea.rudolf.keenetic.link No access odroid 192.168.1.96 HTTP 3002
    hermes.rudolf.keenetic.link Public xu4_lan 192.168.1.114 HTTP 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 2375 or 2376, 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_squash with root_squash after validating Hermes UID/GID behavior, or evaluate Kerberos-backed NFS with sec=krb5/sec=krb5p in 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 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; ordinary HTTP requests are redirected to HTTPS. Traefik ACME storage must be persistent. Router changes remain manual; the operational procedure is documented in 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.

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.