ginskill-init 2.7.0

package/skills/traefik/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: traefik
+description: |
+  **Traefik Reverse Proxy Expert**: Production patterns for configuring Traefik v3 — routing, middleware, TLS/ACME, Docker Compose, Kubernetes CRDs, load balancing, observability, security hardening, CI/CD, and DevOps.
+  - MANDATORY TRIGGERS: traefik, reverse proxy, ingress controller, load balancer, traefik config, traefik middleware, traefik router, traefik service, traefik docker, traefik kubernetes, traefik TLS, traefik ACME, let's encrypt, traefik dashboard, traefik labels, IngressRoute, ForwardAuth, rate limit traefik, traefik compose, traefik helm, traefik CRD, traefik websocket, traefik grpc, traefik TCP, traefik UDP, traefik canary, traefik blue-green, traefik security headers, traefik monitoring, traefik prometheus
+  - Use this skill when building, configuring, deploying, debugging, or reviewing Traefik proxy setups in any environment (Docker, Kubernetes, bare metal, cloud).
+allowed-tools: Read, Grep, Glob, Bash, Write, Edit
+argument-hint: "[topic: config|middleware|tls|docker|k8s|security|cicd|monitoring|auth|tcp-udp|grpc|websocket|ha|performance]"
+---
+
+# Traefik v3 Expert Guide
+
+Traefik is a cloud-native reverse proxy and load balancer. Current stable: **v3.6.x**.
+
+## Quick Reference
+
+| Topic | Doc |
+|-------|-----|
+| Core config (static/dynamic, entrypoints, routers, services) | `docs/core-config.md` |
+| Middleware (headers, rate-limit, auth, compress, chain) | `docs/middleware.md` |
+| TLS, ACME, Let's Encrypt, mTLS | `docs/tls-acme.md` |
+| Docker Compose patterns | `docs/docker-compose.md` |
+| Kubernetes CRDs (IngressRoute, Middleware, TLSOption) | `docs/kubernetes.md` |
+| Security hardening | `docs/security.md` |
+| CI/CD, blue-green, canary, GitOps | `docs/cicd-devops.md` |
+| Monitoring, metrics, tracing, logging | `docs/monitoring.md` |
+| ForwardAuth (Authelia, Authentik, OAuth2 Proxy) | `docs/auth-providers.md` |
+| TCP/UDP, gRPC, WebSocket routing | `docs/advanced-routing.md` |
+| High availability & performance tuning | `docs/ha-performance.md` |
+| Distributed config (Redis, Consul, etcd) | `docs/distributed-config.md` |
+
+## Architecture Model
+
+```
+Internet → EntryPoints → Routers (rules + middleware) → Services → Backends
+              ↑                    ↑                        ↑
+         Static config      Dynamic config           Dynamic config
+```
+
+**Static config** (loaded at startup): entrypoints, providers, cert resolvers, API/dashboard.
+Set via `traefik.yml`, CLI flags, or env vars.
+
+**Dynamic config** (hot-reloaded): routers, services, middlewares, TLS options.
+Provided by: Docker labels, Kubernetes CRDs, file provider, Consul, etcd, Redis.
+
+## Key Patterns
+
+### Docker: Expose a service
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.myapp.rule=Host(`app.example.com`)"
+  - "traefik.http.routers.myapp.entrypoints=websecure"
+  - "traefik.http.routers.myapp.tls.certresolver=letsencrypt"
+  - "traefik.http.services.myapp.loadbalancer.server.port=8080"
+```
+
+### Kubernetes: IngressRoute
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: myapp
+spec:
+  entryPoints: [websecure]
+  routes:
+    - match: Host(`app.example.com`)
+      kind: Rule
+      services:
+        - name: myapp-svc
+          port: 80
+  tls:
+    certResolver: letsencrypt
+```
+
+### Security headers (apply globally)
+```yaml
+http:
+  middlewares:
+    security-headers:
+      headers:
+        browserXssFilter: true
+        contentTypeNosniff: true
+        frameDeny: true
+        stsIncludeSubdomains: true
+        stsPreload: true
+        stsSeconds: 31536000
+```
+
+## When Using This Skill
+
+1. Read the relevant `docs/` file based on the user's topic
+2. Provide production-ready configs, not toy examples
+3. Always include security best practices
+4. Specify Traefik v3 syntax (v2 syntax differs)
+5. Warn about common pitfalls (exposed dashboard, no rate limiting, TLS misconfig)
+
+## Common Pitfalls
+
+- **Never** use `api.insecure: true` in production
+- **Always** set `exposedByDefault: false` for Docker provider
+- **Always** configure `forwardedHeaders.trustedIPs` when behind a load balancer
+- Mount Docker socket **read-only** (`:ro`) or use a socket proxy
+- Wildcard certs require DNS-01 challenge (HTTP-01 won't work)
+- Set `sniStrict: true` to reject connections without matching SNI

package/skills/traefik/docs/advanced-routing.md

@@ -0,0 +1,186 @@
+# Advanced Routing: TCP, UDP, gRPC, WebSocket
+
+## TCP Routing
+
+```yaml
+# Static config - entrypoints
+entryPoints:
+  mysql:
+    address: ":3306"
+  postgres:
+    address: ":5432"
+  ssh:
+    address: ":2222"
+
+# Dynamic config
+tcp:
+  routers:
+    mysql-router:
+      entryPoints: [mysql]
+      rule: "HostSNI(`db.example.com`)"
+      service: mysql-service
+      tls:
+        passthrough: true  # Don't terminate TLS
+
+    ssh-router:
+      entryPoints: [ssh]
+      rule: "HostSNI(`*`)"  # No SNI for plain TCP
+      service: ssh-service
+
+    postgres-tls:
+      entryPoints: [postgres]
+      rule: "HostSNI(`postgres.example.com`)"
+      service: postgres-service
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    mysql-service:
+      loadBalancer:
+        servers:
+          - address: "10.0.0.20:3306"
+          - address: "10.0.0.21:3306"
+
+    ssh-service:
+      loadBalancer:
+        servers:
+          - address: "10.0.0.30:22"
+
+    postgres-service:
+      loadBalancer:
+        servers:
+          - address: "10.0.0.40:5432"
+```
+
+**TLS passthrough**: Traefik reads SNI from ClientHello without terminating TLS.
+**Plain TCP**: Use `HostSNI(`*`)` as catch-all (no TLS = no SNI).
+
+## UDP Routing
+
+```yaml
+entryPoints:
+  dns-udp:
+    address: ":53/udp"
+  wireguard:
+    address: ":51820/udp"
+
+udp:
+  routers:
+    dns-router:
+      entryPoints: [dns-udp]
+      service: dns-service
+
+    wireguard-router:
+      entryPoints: [wireguard]
+      service: wireguard-service
+
+  services:
+    dns-service:
+      loadBalancer:
+        servers:
+          - address: "10.0.0.50:53"
+          - address: "10.0.0.51:53"
+
+    wireguard-service:
+      loadBalancer:
+        servers:
+          - address: "10.0.0.60:51820"
+```
+
+UDP has no path/SNI matching — it's pure load balancing.
+
+## gRPC Routing
+
+```yaml
+http:
+  routers:
+    grpc-router:
+      entryPoints: [websecure]
+      rule: "Host(`grpc.example.com`)"
+      service: grpc-service
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    grpc-service:
+      loadBalancer:
+        servers:
+          - url: "h2c://grpc-backend:50051"  # HTTP/2 cleartext
+        healthCheck:
+          path: /grpc.health.v1.Health/Check
+          scheme: h2c
+          interval: 10s
+```
+
+Docker labels:
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.grpc.rule=Host(`grpc.example.com`)"
+  - "traefik.http.routers.grpc.entrypoints=websecure"
+  - "traefik.http.routers.grpc.tls.certresolver=letsencrypt"
+  - "traefik.http.services.grpc.loadbalancer.server.port=50051"
+  - "traefik.http.services.grpc.loadbalancer.server.scheme=h2c"
+```
+
+### gRPC-Web (browser clients)
+```yaml
+http:
+  middlewares:
+    grpc-web:
+      grpcWeb:
+        allowOrigins:
+          - "https://app.example.com"
+```
+
+## WebSocket
+
+WebSocket works out of the box — no special config needed. The HTTP Upgrade mechanism is handled transparently.
+
+```yaml
+http:
+  routers:
+    ws-router:
+      entryPoints: [websecure]
+      rule: "Host(`ws.example.com`)"
+      service: ws-service
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    ws-service:
+      loadBalancer:
+        servers:
+          - url: "http://websocket-backend:8080"
+        sticky:
+          cookie:
+            name: ws_affinity
+            secure: true
+            httpOnly: true
+```
+
+**Important**: Extend timeouts for long-lived WebSocket connections:
+```yaml
+# traefik.yml (static)
+serversTransport:
+  forwardingTimeouts:
+    dialTimeout: 30s
+    responseHeaderTimeout: 0s  # 0 = no timeout
+    idleConnTimeout: 90s
+```
+
+Sticky sessions are recommended for multi-instance WebSocket backends.
+
+## Server-Sent Events (SSE)
+
+SSE works automatically. Ensure compress middleware excludes `text/event-stream`:
+```yaml
+http:
+  middlewares:
+    compress:
+      compress:
+        excludedContentTypes:
+          - text/event-stream
+```
+
+Set `responseHeaderTimeout: 0s` to prevent premature connection closure.

package/skills/traefik/docs/auth-providers.md

@@ -0,0 +1,137 @@
+# ForwardAuth with Identity Providers
+
+## Authelia
+
+```yaml
+http:
+  middlewares:
+    authelia:
+      forwardAuth:
+        address: "http://authelia:9091/api/authz/forward-auth"
+        trustForwardHeader: true
+        authResponseHeaders:
+          - Remote-User
+          - Remote-Groups
+          - Remote-Name
+          - Remote-Email
+
+    authelia-basic:
+      forwardAuth:
+        address: "http://authelia:9091/api/authz/forward-auth/basic"
+        trustForwardHeader: true
+        authResponseHeaders:
+          - Remote-User
+          - Remote-Groups
+```
+
+Docker label:
+```yaml
+- "traefik.http.routers.myapp.middlewares=authelia@file"
+```
+
+## Authentik
+
+```yaml
+http:
+  middlewares:
+    authentik:
+      forwardAuth:
+        address: "http://authentik-outpost:9000/outpost.goauthentik.io/auth/traefik"
+        trustForwardHeader: true
+        authResponseHeaders:
+          - X-authentik-username
+          - X-authentik-groups
+          - X-authentik-email
+          - X-authentik-name
+          - X-authentik-uid
+          - X-authentik-jwt
+          - X-authentik-meta-jwks
+          - X-authentik-meta-outpost
+          - X-authentik-meta-provider
+          - X-authentik-meta-app
+          - X-authentik-meta-version
+```
+
+## OAuth2 Proxy
+
+Docker Compose:
+```yaml
+services:
+  oauth2-proxy:
+    image: quay.io/oauth2-proxy/oauth2-proxy:latest
+    environment:
+      - OAUTH2_PROXY_PROVIDER=google
+      - OAUTH2_PROXY_CLIENT_ID=xxx.apps.googleusercontent.com
+      - OAUTH2_PROXY_CLIENT_SECRET=secret
+      - OAUTH2_PROXY_COOKIE_SECRET=32-byte-base64-encoded
+      - OAUTH2_PROXY_EMAIL_DOMAINS=example.com
+      - OAUTH2_PROXY_HTTP_ADDRESS=0.0.0.0:4180
+      - OAUTH2_PROXY_REVERSE_PROXY=true
+      - OAUTH2_PROXY_SET_XAUTHREQUEST=true
+    networks: [proxy]
+```
+
+Middleware:
+```yaml
+http:
+  middlewares:
+    oauth2-proxy:
+      forwardAuth:
+        address: "http://oauth2-proxy:4180/oauth2/auth"
+        trustForwardHeader: true
+        authResponseHeaders:
+          - X-Auth-Request-User
+          - X-Auth-Request-Email
+          - X-Auth-Request-Access-Token
+          - Set-Cookie
+```
+
+## Keycloak (via OAuth2 Proxy)
+
+```yaml
+services:
+  oauth2-proxy:
+    image: quay.io/oauth2-proxy/oauth2-proxy:latest
+    environment:
+      - OAUTH2_PROXY_PROVIDER=keycloak-oidc
+      - OAUTH2_PROXY_OIDC_ISSUER_URL=https://keycloak.example.com/realms/myrealm
+      - OAUTH2_PROXY_CLIENT_ID=traefik
+      - OAUTH2_PROXY_CLIENT_SECRET=secret
+      - OAUTH2_PROXY_COOKIE_SECRET=32-byte-base64
+      - OAUTH2_PROXY_EMAIL_DOMAINS=*
+      - OAUTH2_PROXY_HTTP_ADDRESS=0.0.0.0:4180
+      - OAUTH2_PROXY_REVERSE_PROXY=true
+      - OAUTH2_PROXY_SET_XAUTHREQUEST=true
+      - OAUTH2_PROXY_PASS_ACCESS_TOKEN=true
+```
+
+## BasicAuth (simple)
+
+Generate password: `htpasswd -nB admin`
+
+```yaml
+http:
+  middlewares:
+    basic-auth:
+      basicAuth:
+        users:
+          - "admin:$2y$05$hash..."
+        removeHeader: true
+```
+
+Docker label (escape `$` with `$$`):
+```yaml
+- "traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$05$$hash..."
+```
+
+## DigestAuth
+
+```yaml
+http:
+  middlewares:
+    digest-auth:
+      digestAuth:
+        users:
+          - "admin:traefik:hash"
+        removeHeader: true
+```