MahmoudEmad/herolib
1
0
Fork 0
Code Issues 55 Pull Requests 1 Actions Packages Projects Releases 26 Wiki Activity

...

Browse Source
This commit is contained in:
despiegk
2025-08-24 16:40:07 +02:00
parent 8532373e7e
commit a2a9b07238
5 changed files with 1258 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
lib/osal/traefik/specs/entrypoints.md Normal file
View File

@@ -0,0 +1,424 @@
# Traefik EntryPoints — Concise Guide (v3)
> Source docs: Traefik “Routing & Load Balancing → EntryPoints” and “Reference → Install Configuration → EntryPoints” (links in chat).
## What are EntryPoints
EntryPoints are the network entry points into Traefik. They define **which port and protocol (TCP/UDP)** Traefik listens on for incoming traffic. An entryPoint can be referenced by routers (HTTP/TCP/UDP).
---
## Quick Configuration Examples
### Port 80 only
```yaml
# Static configuration
entryPoints:
web:
address: ":80"
```
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
```
```bash
# CLI
--entryPoints.web.address=:80
```
### Ports 80 & 443
```yaml
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
```
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
```
```bash
--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
```
### UDP on port 1704
```yaml
entryPoints:
streaming:
address: ":1704/udp"
```
```toml
[entryPoints]
[entryPoints.streaming]
address = ":1704/udp"
```
```bash
--entryPoints.streaming.address=:1704/udp
```
### TCP **and** UDP on the same port (3179)
```yaml
entryPoints:
tcpep:
address: ":3179" # TCP
udpep:
address: ":3179/udp" # UDP
```
```toml
[entryPoints]
[entryPoints.tcpep]
address = ":3179"
[entryPoints.udpep]
address = ":3179/udp"
```
```bash
--entryPoints.tcpep.address=:3179
--entryPoints.udpep.address=:3179/udp
```
### Listen on specific IPs only
```yaml
entryPoints:
specificIPv4:
address: "192.168.2.7:8888"
specificIPv6:
address: "[2001:db8::1]:8888"
```
```toml
[entryPoints.specificIPv4]
address = "192.168.2.7:8888"
[entryPoints.specificIPv6]
address = "[2001:db8::1]:8888"
```
```bash
--entryPoints.specificIPv4.address=192.168.2.7:8888
--entryPoints.specificIPv6.address=[2001:db8::1]:8888
```
---
## General Structure (Static Configuration)
```yaml
entryPoints:
<name>:
address: ":8888" # or ":8888/tcp" or ":8888/udp"
http2:
maxConcurrentStreams: 250
http3:
advertisedPort: 443 # requires TLS; see notes
transport:
lifeCycle:
requestAcceptGraceTimeout: 42s
graceTimeOut: 42s
respondingTimeouts:
readTimeout: 60s
writeTimeout: 0s
idleTimeout: 180s
proxyProtocol:
insecure: true # trust all (testing only)
trustedIPs:
- "127.0.0.1"
- "192.168.0.1"
forwardedHeaders:
insecure: true # trust all (testing only)
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
connection:
- "foobar"
```
```toml
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.http2]
maxConcurrentStreams = 250
[entryPoints.name.http3]
advertisedPort = 443
[entryPoints.name.transport]
[entryPoints.name.transport.lifeCycle]
requestAcceptGraceTimeout = "42s"
graceTimeOut = "42s"
[entryPoints.name.transport.respondingTimeouts]
readTimeout = "60s"
writeTimeout = "0s"
idleTimeout = "180s"
[entryPoints.name.proxyProtocol]
insecure = true
trustedIPs = ["127.0.0.1", "192.168.0.1"]
[entryPoints.name.forwardedHeaders]
insecure = true
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
connection = ["foobar"]
```
```bash
--entryPoints.name.address=:8888
--entryPoints.name.http2.maxConcurrentStreams=250
--entryPoints.name.http3.advertisedport=443
--entryPoints.name.transport.lifeCycle.requestAcceptGraceTimeout=42s
--entryPoints.name.transport.lifeCycle.graceTimeOut=42s
--entryPoints.name.transport.respondingTimeouts.readTimeout=60s
--entryPoints.name.transport.respondingTimeouts.writeTimeout=0s
--entryPoints.name.transport.respondingTimeouts.idleTimeout=180s
--entryPoints.name.proxyProtocol.insecure=true
--entryPoints.name.proxyProtocol.trustedIPs=127.0.0.1,192.168.0.1
--entryPoints.name.forwardedHeaders.insecure=true
--entryPoints.name.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7
--entryPoints.name.forwardedHeaders.connection=foobar
```
---
## Key Options (Explained)
### `address`
- Format: `[host]:port[/tcp|/udp]`. If protocol omitted ⇒ **TCP**.
- To use **both TCP & UDP** on the same port, define **two** entryPoints (one per protocol).
### `allowACMEByPass` (bool, default **false**)
- Allow user-defined routers to handle **ACME HTTP/TLS challenges** instead of Traefik’s built-in handlers (useful if services also run their own ACME).
```yaml
entryPoints:
foo:
allowACMEByPass: true
```
### `reusePort` (bool, default **false**)
- Enables the OS `SO_REUSEPORT` option: multiple Traefik processes (or entryPoints) can **listen on the same TCP/UDP port**; the kernel load-balances incoming connections.
- Supported on **Linux, FreeBSD, OpenBSD, Darwin**.
- Example (same port, different hosts/IPs):
```yaml
entryPoints:
web:
address: ":80"
reusePort: true
privateWeb:
address: "192.168.1.2:80"
reusePort: true
```
### `asDefault` (bool, default **false**)
- Marks this entryPoint as **default** for HTTP/TCP routers **that don’t specify** `entryPoints`.
```yaml
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
asDefault: true
```
- UDP entryPoints are **never** part of the default list.
- Built-in `traefik` entryPoint is **always excluded**.
### HTTP/2
- `http2.maxConcurrentStreams` (default **250**): max concurrent streams per connection.
### HTTP/3
- Enable by adding `http3: {}` (on a **TCP** entryPoint with **TLS**).
- When enabled on port **N**, Traefik also opens **UDP N** for HTTP/3.
- `http3.advertisedPort`: override the UDP port advertised via `alt-svc` (useful behind a different public port).
### Forwarded Headers
- Trust `X-Forwarded-*` only from `forwardedHeaders.trustedIPs`, or set `forwardedHeaders.insecure: true` (testing only).
- `forwardedHeaders.connection`: headers listed here are allowed to pass through the middleware chain before Traefik drops `Connection`-listed headers per RFC 7230.
### Transport Timeouts
- `transport.respondingTimeouts.readTimeout` (default **60s**): max duration to read the entire request (incl. body).
- `transport.respondingTimeouts.writeTimeout` (default **0s**): max duration for writing the response (0 = disabled).
- `transport.respondingTimeouts.idleTimeout` (default **180s**): max keep-alive idle time.
### Transport LifeCycle (graceful shutdown)
- `transport.lifeCycle.requestAcceptGraceTimeout` (default **0s**): keep accepting requests **before** starting graceful termination.
- `transport.lifeCycle.graceTimeOut` (default **10s**): time to let in-flight requests finish **after** Traefik stops accepting new ones.
### ProxyProtocol
- Enable accepting the **HAProxy PROXY** header and/or trust only from specific IPs.
```yaml
entryPoints:
name:
proxyProtocol:
insecure: true # trust all (testing only)
trustedIPs:
- "127.0.0.1"
- "192.168.0.1"
```
---
## HTTP Options (per entryPoint)
### Redirection → `http.redirections.entryPoint`
Redirect everything on one entryPoint to another (often `web` → `websecure`), and optionally change scheme.
```yaml
entryPoints:
web:
address: ":80"
http:
redirections:
entryPoint:
to: websecure # or ":443"
scheme: https # default is https
permanent: true # 308/301
```
```toml
[entryPoints.web.http.redirections]
entryPoint = "websecure"
scheme = "https"
permanent = true
```
- `http.redirections.entryPoint.priority`: default priority for routers bound to the entryPoint (default `2147483646`).
### Encode Query Semicolons → `http.encodeQuerySemicolons` (bool, default **false**)
- If `true`, non-encoded semicolons in the query string are **encoded** before forwarding (prevents interpreting `;` as query parameter separators).
### SanitizePath → `http.sanitizePath` (bool, default **false**)
- Enable request **path sanitization/normalization** before routing.
### Middlewares → `http.middlewares`
Apply middlewares by name (with provider suffix) **to all routers attached to this entryPoint**.
```yaml
entryPoints:
websecure:
address: ":443"
tls: {}
middlewares:
- auth@kubernetescrd
- strip@kubernetescrd
```
### TLS → `http.tls`
Attach TLS options/resolvers and SNI domains at the entryPoint level (common for `websecure`).
```yaml
# YAML
entryPoints:
websecure:
address: ":443"
http:
tls:
options: foobar
certResolver: leresolver
domains:
- main: example.com
sans:
- foo.example.com
- bar.example.com
- main: test.com
sans:
- foo.test.com
- bar.test.com
```
```bash
--entryPoints.websecure.http.tls.options=foobar
--entryPoints.websecure.http.tls.certResolver=leresolver
--entryPoints.websecure.http.tls.domains[0].main=example.com
--entryPoints.websecure.http.tls.domains[0].sans=foo.example.com,bar.example.com
--entryPoints.websecure.http.tls.domains[1].main=test.com
--entryPoints.websecure.http.tls.domains[1].sans=foo.test.com,bar.test.com
```
---
## UDP Options
### `udp.timeout` (default **3s**)
Release idle UDP session resources after this duration.
```yaml
entryPoints:
foo:
address: ":8000/udp"
udp:
timeout: 10s
```
```toml
[entryPoints.foo]
address = ":8000/udp"
[entryPoints.foo.udp]
timeout = "10s"
```
```bash
--entryPoints.foo.address=:8000/udp
--entryPoints.foo.udp.timeout=10s
```
---
## Systemd Socket Activation
- Traefik supports **systemd socket activation**. If an fd name matches an entryPoint name, Traefik uses that fd as the listener.
```bash
systemd-socket-activate -l 80 -l 443 --fdname web:websecure ./traefik --entrypoints.web --entrypoints.websecure
```
- If using UDP with socket activation, the entryPoint address must include `/udp` (e.g., `--entrypoints.my-udp-entrypoint.address=/udp`).
- **Docker** does not support socket activation; **Podman** does.
- Each systemd socket file should define a **single** Listen directive, **except** for HTTP/3 which needs **both** `ListenStream` and `ListenDatagram` (same port). To run TCP **and** UDP on the same port, use **separate** socket files bound to different entryPoint names.
---
## Observability Options (per entryPoint)
> These control **defaults**; a router’s own observability config can opt out.
```yaml
entryPoints:
foo:
address: ":8000"
observability:
accessLogs: false # default true
metrics: false # default true
tracing: false # default true
```
```toml
[entryPoints.foo]
address = ":8000"
[entryPoints.foo.observability]
accessLogs = false
metrics = false
tracing = false
```
```bash
--entryPoints.foo.observability.accessLogs=false
--entryPoints.foo.observability.metrics=false
--entryPoints.foo.observability.tracing=false
```
---
## Helm Chart Note
The Helm chart creates these entryPoints by default: `web` (80), `websecure` (443), `traefik` (8080), `metrics` (9100). `web` and `websecure` are exposed by default via a Service. You can override everything via values or `additionalArguments`.
---
## Quick Reference (selected fields)
| Field | Description | Default |
|---|---|---|
| `address` | Listener address & protocol `[host]:port[/tcp\|/udp]` | — |
| `asDefault` | Include in default entryPoints list for HTTP/TCP routers | `false` |
| `allowACMEByPass` | Let custom routers handle ACME challenges | `false` |
| `reusePort` | Enable `SO_REUSEPORT` to share the same port across processes | `false` |
| `http2.maxConcurrentStreams` | Max concurrent HTTP/2 streams per connection | `250` |
| `http3.advertisedPort` | UDP port advertised for HTTP/3 `alt-svc` | (entryPoint port) |
| `forwardedHeaders.trustedIPs` | IPs/CIDRs trusted for `X-Forwarded-*` | — |
| `forwardedHeaders.insecure` | Always trust forwarded headers | `false` |
| `transport.respondingTimeouts.readTimeout` | Max duration to read the request | `60s` |
| `transport.respondingTimeouts.writeTimeout` | Max duration to write the response | `0s` |
| `transport.respondingTimeouts.idleTimeout` | Keep-alive idle timeout | `180s` |
| `transport.lifeCycle.requestAcceptGraceTimeout` | Accept requests before graceful stop | `0s` |
| `transport.lifeCycle.graceTimeOut` | Time to finish in-flight requests | `10s` |
| `proxyProtocol.{insecure,trustedIPs}` | Accept PROXY headers (globally or from list) | — |
| `http.redirections.entryPoint.{to,scheme,permanent,priority}` | Redirect all requests on this entryPoint | `scheme=https`, `permanent=false`, `priority=2147483646` |
| `http.encodeQuerySemicolons` | Encode unescaped `;` in query string | `false` |
| `http.sanitizePath` | Normalize/sanitize request paths | `false` |
| `http.middlewares` | Middlewares applied to routers on this entryPoint | — |
| `http.tls` | TLS options/resolver/SNI domains at entryPoint level | — |
| `udp.timeout` | Idle session timeout for UDP routing | `3s` |
| `observability.{accessLogs,metrics,tracing}` | Defaults for router observability | `true` |
---
_This cheat sheet aggregates the salient bits from the official docs for quick use in config files._

183
lib/osal/traefik/specs/middleware.md Normal file
View File

@@ -0,0 +1,183 @@
Here’s the updated Markdown document, now enriched with direct links to the individual middleware reference pages to help you navigate easily.
---
# Traefik Proxy — Middlewares (Overview)
Middlewares are components you attach to **routers** to tweak requests before they reach a **service** (or to tweak responses before they reach clients). They can modify paths and headers, handle redirections, add authentication, rate-limit, and more. Multiple middlewares using the same protocol can be **chained** to fit complex scenarios. ([Overview page]({doc.traefik.io/traefik/middlewares/overview/})) ([Traefik Docs][1], [Traefik Docs][2])
> **Note — Provider Namespace**
> The “Providers Namespace” concept from Configuration Discovery also applies to middlewares (e.g., `foo@docker`, `bar@file`). ([Traefik Docs][1], [Traefik Docs][3])
---
## Configuration Examples
Examples showing how to **define** a middleware and **attach** it to a router across different providers. ([Traefik Docs][2])
<details>
<summary>Docker & Swarm (labels)</summary>
```yaml
whoami:
image: traefik/whoami
labels:
- "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo"
- "traefik.http.routers.router1.middlewares=foo-add-prefix@docker"
```
</details>
<details>
<summary>Kubernetes CRD (IngressRoute)</summary>
```yaml
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: stripprefix
spec:
stripPrefix:
prefixes:
- /stripit
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroute
spec:
routes:
- match: Host(`example.com`)
kind: Rule
services:
- name: my-svc
port: 80
middlewares:
- name: stripprefix
```
</details>
<details>
<summary>Consul Catalog (labels)</summary>
```text
"traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo"
"traefik.http.routers.router1.middlewares=foo-add-prefix@consulcatalog"
```
</details>
<details>
<summary>File Provider (YAML)</summary>
```yaml
http:
routers:
router1:
rule: "Host(`example.com`)"
service: myService
middlewares:
- "foo-add-prefix"
middlewares:
foo-add-prefix:
addPrefix:
prefix: "/foo"
services:
myService:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
```
</details>
<details>
<summary>File Provider (TOML)</summary>
```toml
[http.routers.router1]
rule = "Host(`example.com`)"
service = "myService"
middlewares = ["foo-add-prefix"]
[http.middlewares.foo-add-prefix.addPrefix]
prefix = "/foo"
[http.services.myService.loadBalancer.servers]
url = "http://127.0.0.1:80"
```
</details>
---
## Available Middlewares
**HTTP Middlewares** — the complete list is detailed in the HTTP middlewares section:
AddPrefix, BasicAuth, Buffering, Chain, CircuitBreaker, Compress, ContentType, DigestAuth, Errors, ForwardAuth, GrpcWeb, Headers, IPAllowList / IPWhiteList, InFlightReq, PassTLSClientCert, RateLimit, RedirectRegex, RedirectScheme, ReplacePath, ReplacePathRegex, Retry, StripPrefix, StripPrefixRegex. ([Traefik Docs][4])
**TCP Middlewares** — covered in the TCP middlewares section:
InFlightConn, IPAllowList / IPWhiteList. ([Traefik Docs][5])
---
## Middleware Reference Links
Below are direct links to documentation for some of the most commonly used middlewares:
* **[AddPrefix](https://doc.traefik.io/traefik/middlewares/http/addprefix/)** — prepends a path segment to requests ([Traefik Docs][6], [Traefik Docs][7])
* **[BasicAuth](https://doc.traefik.io/traefik/middlewares/http/basicauth/)** — adds basic HTTP authentication ([Traefik Docs][8])
* **[IPAllowList (HTTP)](https://doc.traefik.io/traefik/middlewares/http/ipallowlist/)** — allows access only from specified IPs ([Traefik Docs][9])
* **[IPWhiteList (TCP)](https://doc.traefik.io/traefik/middlewares/tcp/ipwhitelist/)** — deprecated way to white-list TCP client IPs; prefer IPAllowList ([Traefik Docs][5])
(These are just a few examples—feel free to ask for more specific middleware links if needed.)
---
### Optional: Full Document Outline
If you’d like the full reference structure in Markdown, here's a possible outline to expand further:
```
# Traefik Middlewares Reference
## Overview (link)
- Overview of Middlewares
## Configuration Examples
- Docker / Swarm
- Kubernetes CRD
- Consul Catalog
- File (YAML & TOML)
## HTTP Middlewares
- AddPrefix — [AddPrefix link]
- BasicAuth — [BasicAuth link]
- Buffering — [Buffering link]
- Chain — [Chain link]
- ... (and so on)
## TCP Middlewares
- IPAllowList (TCP) — [IPAllowList TCP link]
- (Any other TCP middleware)
## Additional Resources
- Kubernetes CRD Middleware — [CRD link]
- Routers and middleware chaining — [Routers link]
- Dynamic configuration via File provider — [File provider link]
```
[1]: https://doc.traefik.io/traefik/v2.2/middlewares/overview/?utm_source=chatgpt.com "Middlewares"
[2]: https://doc.traefik.io/traefik/middlewares/overview/?utm_source=chatgpt.com "Traefik Proxy Middleware Overview"
[3]: https://doc.traefik.io/traefik/reference/dynamic-configuration/file/?utm_source=chatgpt.com "Traefik File Dynamic Configuration"
[4]: https://doc.traefik.io/traefik/middlewares/http/overview/?utm_source=chatgpt.com "Traefik Proxy HTTP Middleware Overview"
[5]: https://doc.traefik.io/traefik/middlewares/tcp/ipwhitelist/?utm_source=chatgpt.com "Traefik TCP Middlewares IPWhiteList"
[6]: https://doc.traefik.io/traefik/routing/routers/?utm_source=chatgpt.com "Traefik Routers Documentation"
[7]: https://doc.traefik.io/traefik/middlewares/http/addprefix/?utm_source=chatgpt.com "Traefik AddPrefix Documentation"
[8]: https://doc.traefik.io/traefik/middlewares/http/basicauth/?utm_source=chatgpt.com "Traefik BasicAuth Documentation"
[9]: https://doc.traefik.io/traefik/middlewares/http/ipallowlist/?utm_source=chatgpt.com "Traefik HTTP Middlewares IPAllowList"

159
lib/osal/traefik/specs/redis.md Normal file
View File

@@ -0,0 +1,159 @@
# Traefik + Redis (KV provider): how to use it, where keys go, and how to notify Traefik
## 1) Enable the Redis provider (static config)
Add the Redis provider to Traefik’s **install/static** configuration (YAML example):
```yaml
providers:
redis:
endpoints: # one or more Redis endpoints
- "127.0.0.1:6379"
rootKey: "traefik" # KV root/prefix (default: traefik)
db: 0 # optional
username: "" # optional
password: "" # optional
tls: # optional (use if Redis is TLS-enabled)
ca: /path/to/ca.crt
cert: /path/to/client.crt
key: /path/to/client.key
insecureSkipVerify: false
sentinel: # optional (if using Redis Sentinel)
masterName: my-master
# username/password/latencyStrategy/randomStrategy/replicaStrategy/useDisconnectedReplicas available
```
CLI equivalents (examples):
`--providers.redis.endpoints=127.0.0.1:6379 --providers.redis.rootkey=traefik --providers.redis.db=0` (see docs for all flags). ([Traefik Docs][1])
> **Important:** Traefik only *reads/watches* dynamic (routing) configuration from Redis. It doesn’t store anything there automatically. You populate keys yourself (see §3). ([Traefik Docs][1])
---
## 2) “Notifying” Traefik about changes (Redis keyspace notifications)
To have Traefik react to updates **without restart**, Redis must have **keyspace notifications** enabled. A safe, common setting is:
```bash
# temporary (runtime):
redis-cli CONFIG SET notify-keyspace-events AKE
# verify:
redis-cli CONFIG GET notify-keyspace-events
```
Or set `notify-keyspace-events AKE` in `redis.conf`, or via your cloud provider’s parameter group (e.g., ElastiCache / Memorystore). ([Traefik Docs][1], [Redis][2], [Traefik Labs Community Forum][3])
> Notes
>
> * Managed Redis services often **disable** these notifications by default for performance reasons—enable them explicitly. ([Traefik Docs][1])
> * `AKE` means “all” (`A`) generic/string/list/set/zset/stream + keyspace (`K`) + keyevent (`E`) messages. ([TECHCOMMUNITY.MICROSOFT.COM][4])
---
## 3) Where values must live in Redis (key layout)
Traefik expects a **hierarchical path** under `rootKey` (default `traefik`). You set **one string value per path**. Examples below show minimal keys for an HTTP route + service.
### 3.1 Minimal HTTP router + service
```
traefik/http/routers/myrouter/rule = Host(`kv.example.com`)
traefik/http/routers/myrouter/entryPoints/0 = web
traefik/http/routers/myrouter/entryPoints/1 = websecure
traefik/http/routers/myrouter/service = myservice
traefik/http/services/myservice/loadBalancer/servers/0/url = http://10.0.10.5:8080
traefik/http/services/myservice/loadBalancer/servers/1/url = http://10.0.10.6:8080
```
(Write these with `redis-cli SET <key> "<value>"`.) ([Traefik Docs][5])
### 3.2 Add middlewares and TLS (optional)
```
traefik/http/routers/myrouter/middlewares/0 = auth
traefik/http/routers/myrouter/middlewares/1 = prefix
traefik/http/routers/myrouter/tls = true
traefik/http/routers/myrouter/tls/certResolver = myresolver
traefik/http/routers/myrouter/tls/domains/0/main = example.org
traefik/http/routers/myrouter/tls/domains/0/sans/0 = dev.example.org
```
([Traefik Docs][5])
### 3.3 TCP example (e.g., pass-through services)
```
traefik/tcp/routers/mytcprouter/rule = HostSNI(`*`)
traefik/tcp/routers/mytcprouter/entryPoints/0 = redis-tcp
traefik/tcp/routers/mytcprouter/service = mytcpservice
traefik/tcp/routers/mytcprouter/tls/passthrough = true
traefik/tcp/services/mytcpservice/loadBalancer/servers/0/address = 10.0.10.7:6379
```
([Traefik Docs][6])
> The full KV reference (all keys for routers/services/middlewares/TLS/options/observability) is here and shows many more fields you can set. ([Traefik Docs][6])
---
## 4) End-to-end quickstart (commands you can paste)
```bash
# 1) Enable keyspace notifications (see §2)
redis-cli CONFIG SET notify-keyspace-events AKE
# 2) Create minimal HTTP route + service (see §3.1)
redis-cli SET traefik/http/routers/myrouter/rule "Host(`kv.example.com`)"
redis-cli SET traefik/http/routers/myrouter/entryPoints/0 "web"
redis-cli SET traefik/http/routers/myrouter/entryPoints/1 "websecure"
redis-cli SET traefik/http/routers/myrouter/service "myservice"
redis-cli SET traefik/http/services/myservice/loadBalancer/servers/0/url "http://10.0.10.5:8080"
redis-cli SET traefik/http/services/myservice/loadBalancer/servers/1/url "http://10.0.10.6:8080"
```
Traefik will pick these up automatically (no restart) once keyspace notifications are on. ([Traefik Docs][1])
---
## 5) Operational tips / gotchas
* **Managed Redis**: enable `notify-keyspace-events` (e.g., ElastiCache parameter group; Memorystore config). Without it, Traefik won’t react to updates. ([Traefik Docs][1], [Traefik Labs Community Forum][3])
* **Persistence**: if you want the config to survive Redis restarts, enable AOF or snapshots per your ops policy. (General Redis ops guidance.) ([JupyterHub Traefik Proxy][7])
* **Sentinel / TLS**: configure the provider fields accordingly (see §1). ([Traefik Docs][1])
* **Deletions**: some users reported recent Traefik versions not always propagating *deletions* from Redis the same way as updates—test your workflow; if needed, set empty values or overwrite keys. Track open issues. ([GitHub][8], [Traefik Labs Community Forum][9])
---
## 6) Checklist
1. Traefik started with `providers.redis` pointing at your Redis. ([Traefik Docs][1])
2. `notify-keyspace-events` enabled (e.g., `AKE`). ([Traefik Docs][1], [Redis][2])
3. Keys created under `rootKey` (default `traefik`) following the **KV path schema** shown above. ([Traefik Docs][5])
4. Verify in Traefik dashboard/API that routers/services appear. (General provider behavior.) ([Traefik Docs][10])
---
### Sources
* Traefik Redis provider docs (static options & keyspace note). ([Traefik Docs][1])
* KV dynamic configuration reference (full key paths). ([Traefik Docs][6])
* KV provider routing examples (HTTP services/routers). ([Traefik Docs][5])
* Example KV layout (Hub ref, same model). ([Traefik Docs][11])
* Redis keyspace notifications (what `AKE` means). ([Redis][2], [TECHCOMMUNITY.MICROSOFT.COM][4])
If you want, I can output the exact `redis-cli` commands for any specific route/service you plan to add.
[1]: https://doc.traefik.io/traefik/providers/redis/ "Traefik Redis Documentation - Traefik"
[2]: https://redis.io/docs/latest/develop/pubsub/keyspace-notifications/?utm_source=chatgpt.com "Redis keyspace notifications | Docs"
[3]: https://community.traefik.io/t/traefik-not-re-configuring-using-aws-elasticicache-redis-on-change/5227?utm_source=chatgpt.com "Traefik not re-configuring using AWS Elasticicache Redis ..."
[4]: https://techcommunity.microsoft.com/blog/azurepaasblog/redis-keyspace-events-notifications/1551134?utm_source=chatgpt.com "Redis Keyspace Events Notifications"
[5]: https://doc.traefik.io/traefik/routing/providers/kv/ "Traefik Routing Configuration with KV stores - Traefik"
[6]: https://doc.traefik.io/traefik/reference/dynamic-configuration/kv/ "Traefik Dynamic Configuration with KV stores - Traefik"
[7]: https://jupyterhub-traefik-proxy.readthedocs.io/en/stable/redis.html?utm_source=chatgpt.com "Using TraefikRedisProxy - JupyterHub Traefik Proxy"
[8]: https://github.com/traefik/traefik/issues/11864?utm_source=chatgpt.com "Traefik does not handle rules deletion from redis kv #11864"
[9]: https://community.traefik.io/t/traefik-does-not-prune-deleted-rules-from-redis-kv/27789?utm_source=chatgpt.com "Traefik does not prune deleted rules from redis KV"
[10]: https://doc.traefik.io/traefik/providers/overview/?utm_source=chatgpt.com "Traefik Configuration Discovery Overview"
[11]: https://doc.traefik.io/traefik-hub/api-gateway/reference/ref-overview?utm_source=chatgpt.com "Install vs Routing Configuration | Traefik Hub Documentation"

229
lib/osal/traefik/specs/routers.md Normal file
View File

@@ -0,0 +1,229 @@
# Traefik Routers — Practical Guide
A **router** connects incoming traffic to a target **service**. It matches requests (or connections), optionally runs **middlewares**, and forwards to the chosen **service**. ([Traefik Docs][1])
---
## Quick examples
```yaml
# Dynamic (file provider) — HTTP: /foo -> service-foo
http:
routers:
my-router:
rule: Path(`/foo`)
service: service-foo
```
```toml
# Dynamic (file provider) — HTTP: /foo -> service-foo
[http.routers.my-router]
rule = "Path(`/foo`)"
service = "service-foo"
```
```yaml
# Dynamic — TCP: all non-TLS on :3306 -> database
tcp:
routers:
to-database:
entryPoints: ["mysql"]
rule: HostSNI(`*`)
service: database
```
```yaml
# Static — define entrypoints
entryPoints:
web: { address: ":80" }
mysql: { address: ":3306" }
```
([Traefik Docs][1])
---
## HTTP Routers
### EntryPoints
* If omitted, an HTTP router listens on all default entry points; set `entryPoints` to scope it. ([Traefik Docs][1])
```yaml
http:
routers:
r1:
rule: Host(`example.com`)
service: s1
entryPoints: ["web","websecure"]
```
### Rule (matchers)
A **rule** activates the router when it matches; then middlewares run, then the request is sent to the service. Common matchers (v3 syntax):
* `Host(...)`, `HostRegexp(...)`
* `Path(...)`, `PathPrefix(...)`, `PathRegexp(...)`
* `Header(...)`, `HeaderRegexp(...)`
* `Method(...)`
* `Query(...)`, `QueryRegexp(...)`
* `ClientIP(...)`
See the full table in the official page. ([Traefik Docs][1])
### Priority
Routers sort by **rule length** (desc) when `priority` is unset. Set `priority` to override (Max: `MaxInt32-1000` on 32-bit, `MaxInt64-1000` on 64-bit). ([Traefik Docs][1])
### Rule Syntax (`ruleSyntax`)
* Traefik v3 introduces a new rule syntax; you can set per-router `ruleSyntax: v2|v3`.
* Default inherits from static `defaultRuleSyntax` (defaults to `v3`). ([Traefik Docs][1])
### Middlewares
Attach a **list** in order; names cannot contain `@`. Applied only if the rule matches. ([Traefik Docs][1])
```yaml
http:
routers:
r-auth:
rule: Path(`/foo`)
middlewares: [authentication]
service: service-foo
```
### Service
Every HTTP router must target an **HTTP service** (not TCP). Some label-based providers auto-create defaults. ([Traefik Docs][1])
### TLS (HTTPS termination)
* Adding a `tls` section makes the router **HTTPS-only** and **terminates TLS** by default.
* To serve **both HTTP and HTTPS**, define **two routers**: one with `tls: {}` and one without.
* `tls.options`, `tls.certResolver`, and `tls.domains` follow the HTTP TLS reference. ([Traefik Docs][1])
### Observability (per-router)
Per-router toggles for `accessLogs`, `metrics`, `tracing`. Router-level settings override entrypoint defaults, but require the global features enabled first. Internal resources obey `AddInternals` guards. ([Traefik Docs][1])
```yaml
http:
routers:
r:
rule: Path(`/foo`)
service: s
observability:
accessLogs: false
metrics: false
tracing: false
```
---
## TCP Routers
### General
* If HTTP and TCP routers listen on the **same entry point**, **TCP routers apply first**; if none matches, HTTP routers take over.
* Names cannot contain `@`. ([Traefik Docs][1])
### EntryPoints & “server-first” protocols
* Omit `entryPoints` → listens on all default.
* For **server-first** protocols (e.g., SMTP), ensure **no TLS routers** exist on that entry point and have **at least one non-TLS TCP router** to avoid deadlocks (both sides waiting). ([Traefik Docs][1])
### Rule (matchers)
* `HostSNI(...)`, `HostSNIRegexp(...)` (for TLS SNI)
* `ClientIP(...)`
* `ALPN(...)`
Same flow: match → middlewares → service. ([Traefik Docs][1])
### Priority & Rule Syntax
* Same priority model as HTTP; set `priority` to override.
* `ruleSyntax: v2|v3` supported per router (example below). ([Traefik Docs][1])
```yaml
tcp:
routers:
r-v3:
rule: ClientIP(`192.168.0.11`) || ClientIP(`192.168.0.12`)
ruleSyntax: v3
service: s1
r-v2:
rule: ClientIP(`192.168.0.11`, `192.168.0.12`)
ruleSyntax: v2
service: s2
```
### Middlewares
Order matters; names cannot contain `@`. ([Traefik Docs][1])
### Services
TCP routers **must** target **TCP services** (not HTTP). ([Traefik Docs][1])
### TLS
* Adding `tls` makes the router **TLS-only**.
* Default is **TLS termination**; set `tls.passthrough: true` to forward encrypted bytes unchanged.
* `tls.options` (cipher suites, versions), `tls.certResolver`, `tls.domains` are supported when `HostSNI` is defined. ([Traefik Docs][1])
```yaml
tcp:
routers:
r-pass:
rule: HostSNI(`db.example.com`)
service: db
tls:
passthrough: true
```
**Postgres STARTTLS:** Traefik can detect Postgres’ STARTTLS negotiation and proceed with TLS routing; prefer client `sslmode=require`. Be careful with TLS passthrough and certain `sslmode` values. ([Traefik Docs][1])
---
## UDP Routers
### General
* UDP has no URL or SNI to match; UDP “routers” are effectively **load-balancers** with no rule criteria.
* Traefik maintains **sessions** (with a **timeout**) to map backend responses to clients. Configure timeout via `entryPoints.<name>.udp.timeout`. Names cannot contain `@`. ([Traefik Docs][1])
### EntryPoints
* Omit `entryPoints` → listens on all **UDP** entry points; specify to scope. ([Traefik Docs][1])
```yaml
udp:
routers:
r:
entryPoints: ["streaming"]
service: s1
```
### Services
UDP routers **must** target **UDP services** (not HTTP/TCP). ([Traefik Docs][1])
---
## Tips & gotchas
* `@` is **not allowed** in router, middleware, or service names. ([Traefik Docs][1])
* To serve the **same route on HTTP and HTTPS**, create **two routers** (with and without `tls`). ([Traefik Docs][1])
* Priority defaults to **rule length**; explicit `priority` wins and is often needed when a specific case should beat a broader matcher. ([Traefik Docs][1])
* **TCP vs HTTP precedence** on the same entry point: **TCP first**. ([Traefik Docs][1])
---
### Sources
Official Traefik docs — **Routers** (HTTP/TCP/UDP), examples, TLS, observability. ([Traefik Docs][1])
If you want this as a separate `.md` file in a specific structure (e.g., your repo), tell me the filename/path and I’ll format it accordingly.
[1]: https://doc.traefik.io/traefik/routing/routers/ "Traefik Routers Documentation - Traefik"

263
lib/osal/traefik/specs/services.md Normal file
View File

@@ -0,0 +1,263 @@
# Traefik Services (HTTP/TCP/UDP)
Services define **how Traefik reaches your backends** and how requests are **load-balanced** across them. Every service has a load balancer—even with a single server. ([Traefik Docs][1])
---
## Quick examples
```yaml
# Dynamic config (file provider)
http:
services:
web:
loadBalancer:
servers:
- url: "http://10.0.0.11:8080/"
- url: "http://10.0.0.12:8080/"
tcp:
services:
db:
loadBalancer:
servers:
- address: "10.0.0.21:5432"
- address: "10.0.0.22:5432"
udp:
services:
dns:
loadBalancer:
servers:
- address: "10.0.0.31:53"
- address: "10.0.0.32:53"
```
([Traefik Docs][1])
---
## HTTP services
### Servers Load Balancer
* **servers\[].url** – each backend instance.
* **preservePath** – keep the path segment of the URL when forwarding (note: not preserved for health-check requests). ([Traefik Docs][1])
```yaml
http:
services:
api:
loadBalancer:
servers:
- url: "http://10.0.0.10/base"
preservePath: true
```
#### Load-balancing strategy
* **WRR (default)** – optional **weight** per server.
* **P2C** – “power of two choices”; picks two random servers, chooses the one with fewer active requests. ([Traefik Docs][1])
```yaml
# WRR with weights
http:
services:
api:
loadBalancer:
servers:
- url: "http://10.0.0.10/"; weight: 2
- url: "http://10.0.0.11/"; weight: 1
# P2C
http:
services:
api:
loadBalancer:
strategy: p2c
servers:
- url: "http://10.0.0.10/"
- url: "http://10.0.0.11/"
- url: "http://10.0.0.12/"
```
([Traefik Docs][1])
#### Sticky sessions
Adds an affinity cookie so subsequent requests hit the same server.
* Works across nested LBs if stickiness is enabled at **each** level.
* If the chosen server becomes unhealthy, Traefik selects a new one and updates the cookie.
* Cookie options: `name`, `secure`, `httpOnly`, `sameSite`, `domain`, `maxAge`. ([Traefik Docs][1])
```yaml
http:
services:
web:
loadBalancer:
sticky:
cookie:
name: app_affinity
secure: true
httpOnly: true
sameSite: lax
domain: example.com
```
#### Health check
Periodically probes backends and **removes unhealthy servers** from rotation.
* HTTP(S): healthy if status is 2xx/3xx (or a configured status).
* gRPC: healthy if it returns `SERVING` (gRPC health v1).
* Options include `path`, `interval`, `timeout`, `scheme`, `hostname`, `port`. ([Traefik Docs][1])
```yaml
http:
services:
web:
loadBalancer:
healthCheck:
path: /health
interval: 10s
timeout: 3s
```
#### Pass Host Header
Controls forwarding of the original `Host` header. **Default: true**. ([Traefik Docs][1])
```yaml
http:
services:
web:
loadBalancer:
passHostHeader: false
```
#### ServersTransport (HTTP)
Fine-tunes the connection from Traefik to your upstreams.
* TLS: `serverName`, `certificates`, `insecureSkipVerify`, `rootCAs`, `peerCertURI`, SPIFFE (`spiffe.ids`, `spiffe.trustDomain`)
* HTTP/2 toggle: `disableHTTP2`
* Pooling: `maxIdleConnsPerHost`
* Timeouts (`forwardingTimeouts`): `dialTimeout`, `responseHeaderTimeout`, `idleConnTimeout`, `readIdleTimeout`, `pingTimeout`
Attach by name via `loadBalancer.serversTransport`. ([Traefik Docs][1])
```yaml
http:
serversTransports:
mtls:
rootCAs:
- /etc/ssl/my-ca.pem
serverName: backend.internal
insecureSkipVerify: false
forwardingTimeouts:
responseHeaderTimeout: "1s"
http:
services:
web:
loadBalancer:
serversTransport: mtls
servers:
- url: "https://10.0.0.10:8443/"
```
#### Response forwarding
Control how Traefik flushes response bytes to clients.
* `flushInterval` (ms): default **100**; negative = flush after each write; streaming responses are auto-flushed. ([Traefik Docs][1])
```yaml
http:
services:
streamy:
loadBalancer:
responseForwarding:
flushInterval: 50
```
---
## Composite HTTP services
### Weighted Round Robin (service)
Combine **services** (not just servers) with weights; health status propagates upward if enabled. ([Traefik Docs][1])
### Mirroring (service)
Send requests to a **main service** and mirror a percentage to others.
* Defaults: `percent` = 0 (no traffic), `mirrorBody` = true, `maxBodySize` = -1 (unlimited).
* Providers: File, CRD IngressRoute.
* Health status can propagate upward (File provider). ([Traefik Docs][1])
```yaml
http:
services:
mirrored-api:
mirroring:
service: appv1
mirrorBody: false
maxBodySize: 1024
mirrors:
- name: appv2
percent: 10
```
### Failover (service)
Route to **fallback** only when **main** is unreachable (relies on HealthCheck).
* Currently available with the **File** provider.
* HealthCheck on a Failover service requires all descendants to also enable it. ([Traefik Docs][1])
```yaml
http:
services:
app:
failover:
service: main
fallback: backup
main:
loadBalancer:
healthCheck: { path: /status, interval: 10s, timeout: 3s }
servers: [{ url: "http://10.0.0.50/" }]
backup:
loadBalancer:
servers: [{ url: "http://10.0.0.60/" }]
```
---
## TCP services (summary)
* **servers\[].address** (`host:port`), optional **tls** to upstream, attach a **ServersTransport** (TCP) with `dialTimeout`, `dialKeepAlive`, `terminationDelay`, TLS/SPIFEE options, and optional **PROXY Protocol** send. ([Traefik Docs][1])
---
## UDP services (summary)
* **servers\[].address** (`host:port`). Weighted round robin supported. ([Traefik Docs][1])
---
## Notes & gotchas
* Stickiness across nested load balancers requires enabling sticky at **each** level, and clients will carry **multiple key/value pairs** in the cookie. ([Traefik Docs][1])
* Health checks: enabling at a parent requires **all descendants** to support/enable it; otherwise service creation fails (applies to Mirroring/Failover health-check sections). ([Traefik Docs][1])
---
**Source:** Traefik “Routing & Load Balancing → Services” (current docs). ([Traefik Docs][1])
[1]: https://doc.traefik.io/traefik/routing/services/ "Traefik Services Documentation - Traefik"