ginskill-init 2.7.0

package/skills/traefik/docs/middleware.md

@@ -0,0 +1,205 @@
+# Traefik Middleware Reference
+
+Middleware sits between routers and services. Applied in order listed on the router.
+
+## HTTP Middlewares
+
+### Headers
+```yaml
+http:
+  middlewares:
+    security-headers:
+      headers:
+        browserXssFilter: true
+        contentTypeNosniff: true
+        frameDeny: true
+        stsIncludeSubdomains: true
+        stsPreload: true
+        stsSeconds: 31536000
+        customFrameOptionsValue: "SAMEORIGIN"
+        referrerPolicy: "strict-origin-when-cross-origin"
+        permissionsPolicy: "camera=(), microphone=(), geolocation=()"
+        contentSecurityPolicy: "default-src 'self'"
+        customResponseHeaders:
+          X-Robots-Tag: "noindex,nofollow"
+          server: ""  # Remove server header
+```
+
+### RateLimit
+```yaml
+rate-limit:
+  rateLimit:
+    average: 100    # Requests per period
+    burst: 50       # Max bucket size
+    period: 1s      # Time window
+    sourceCriterion:
+      ipStrategy:
+        depth: 1    # Extract IP from X-Forwarded-For (depth from right)
+      # OR: requestHeaderName: "X-API-Key"
+      # OR: requestHost: true
+```
+
+### CircuitBreaker
+```yaml
+circuit-breaker:
+  circuitBreaker:
+    expression: "LatencyAtQuantileMS(50.0) > 100 || NetworkErrorRatio() > 0.30 || ResponseCodeRatio(500, 600, 0, 600) > 0.25"
+    checkPeriod: 10s
+    fallbackDuration: 30s
+    recoveryDuration: 60s
+```
+
+### Retry
+```yaml
+retry:
+  retry:
+    attempts: 3
+    initialInterval: 100ms
+```
+
+### Compress
+```yaml
+compress:
+  compress:
+    excludedContentTypes:
+      - text/event-stream
+    minResponseBodyBytes: 1024
+```
+
+### BasicAuth
+```yaml
+basic-auth:
+  basicAuth:
+    users:
+      - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"  # htpasswd -nB admin
+    # OR: usersFile: /etc/traefik/.htpasswd
+    removeHeader: true  # Don't forward auth header to backend
+```
+
+### ForwardAuth
+```yaml
+forward-auth:
+  forwardAuth:
+    address: "http://auth-service:9091/api/authz/forward-auth"
+    trustForwardHeader: true
+    authResponseHeaders:
+      - Remote-User
+      - Remote-Groups
+      - Remote-Email
+```
+
+### RedirectScheme
+```yaml
+redirect-https:
+  redirectScheme:
+    scheme: https
+    permanent: true
+```
+
+### RedirectRegex
+```yaml
+redirect-www:
+  redirectRegex:
+    regex: "^https://www\\.(.+)"
+    replacement: "https://${1}"
+    permanent: true
+```
+
+### StripPrefix
+```yaml
+strip-api:
+  stripPrefix:
+    prefixes:
+      - /api
+    forceSlash: false
+```
+
+### AddPrefix
+```yaml
+add-prefix:
+  addPrefix:
+    prefix: /v2
+```
+
+### IPAllowList
+```yaml
+ip-allowlist:
+  ipAllowList:
+    sourceRange:
+      - "10.0.0.0/8"
+      - "192.168.1.0/24"
+    ipStrategy:
+      depth: 1
+```
+
+### Chain (combine middlewares)
+```yaml
+secured:
+  chain:
+    middlewares:
+      - security-headers
+      - rate-limit
+      - compress
+      - forward-auth
+```
+
+### InFlightReq
+```yaml
+inflight:
+  inFlightReq:
+    amount: 100
+    sourceCriterion:
+      ipStrategy:
+        depth: 1
+```
+
+### Buffering
+```yaml
+buffering:
+  buffering:
+    maxRequestBodyBytes: 10485760   # 10MB
+    maxResponseBodyBytes: 10485760
+    retryExpression: "IsNetworkError() && Attempts() < 2"
+```
+
+### GrpcWeb
+```yaml
+grpc-web:
+  grpcWeb:
+    allowOrigins:
+      - "https://app.example.com"
+```
+
+## Docker Label Syntax
+
+```yaml
+labels:
+  - "traefik.http.middlewares.my-ratelimit.ratelimit.average=100"
+  - "traefik.http.middlewares.my-ratelimit.ratelimit.burst=50"
+  - "traefik.http.routers.myapp.middlewares=my-ratelimit,security-headers@file"
+```
+
+## Kubernetes CRD Syntax
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: rate-limit
+spec:
+  rateLimit:
+    average: 100
+    burst: 50
+```
+
+## Middleware Order
+
+Middleware executes in the order listed on the router. Recommended order:
+1. IPAllowList / IPWhiteList
+2. RateLimit / InFlightReq
+3. ForwardAuth / BasicAuth
+4. Headers (security)
+5. StripPrefix / AddPrefix
+6. Compress
+7. CircuitBreaker
+8. Retry

package/skills/traefik/docs/monitoring.md

@@ -0,0 +1,357 @@
+# Traefik Monitoring, Metrics & Observability
+
+## Prometheus Metrics
+
+### Static Config
+```yaml
+entryPoints:
+  metrics:
+    address: ":8082"
+
+metrics:
+  prometheus:
+    entryPoint: metrics
+    addEntryPointsLabels: true
+    addServicesLabels: true
+    addRoutersLabels: true  # Caution: high cardinality
+    buckets: [0.1, 0.3, 1.2, 5.0]
+```
+
+### Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `traefik_entrypoint_requests_total` | Total requests by entrypoint, method, protocol, code |
+| `traefik_entrypoint_open_connections` | Current open connections |
+| `traefik_service_requests_total` | Requests per service |
+| `traefik_service_request_duration_seconds` | Latency histogram per service |
+| `traefik_service_open_connections` | Open connections per service |
+| `traefik_tls_certs_not_after` | Certificate expiry timestamp |
+| `traefik_config_reloads_total` | Config reload count |
+| `traefik_config_last_reload_success` | Last reload success (0/1) |
+
+### Prometheus Scrape Config
+```yaml
+scrape_configs:
+  - job_name: traefik
+    scrape_interval: 15s
+    static_configs:
+      - targets: ["traefik:8082"]
+    # OR in Kubernetes:
+    kubernetes_sd_configs:
+      - role: pod
+    relabel_configs:
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
+        action: keep
+        regex: true
+```
+
+## OpenTelemetry Tracing
+
+```yaml
+tracing:
+  otlp:
+    http:
+      endpoint: http://otel-collector:4318/v1/traces
+    # OR grpc:
+    #   endpoint: otel-collector:4317
+```
+
+With sampling:
+```yaml
+tracing:
+  sampleRate: 0.1  # Sample 10% of traces
+  otlp:
+    http:
+      endpoint: http://otel-collector:4318/v1/traces
+      headers:
+        Authorization: "Bearer token"
+```
+
+## Access Logs
+
+```yaml
+accessLog:
+  filePath: /var/log/traefik/access.log
+  format: json
+  bufferingSize: 100  # Buffer N lines before writing
+  filters:
+    statusCodes: ["400-499", "500-599"]
+    retryAttempts: true
+    minDuration: 100ms
+  fields:
+    defaultMode: keep
+    names:
+      ClientUsername: drop
+    headers:
+      defaultMode: drop
+      names:
+        User-Agent: keep
+        Authorization: drop
+        Content-Type: keep
+```
+
+### OTLP Log Export (experimental, v3.3+)
+```yaml
+accessLog:
+  otlp:
+    http:
+      endpoint: http://otel-collector:4318/v1/logs
+```
+
+## Application Logs
+
+```yaml
+log:
+  level: WARN       # DEBUG, INFO, WARN, ERROR
+  filePath: /var/log/traefik/traefik.log
+  format: json       # common or json
+  noColor: true
+```
+
+## Grafana Dashboard
+
+Docker Compose with full monitoring stack:
+
+```yaml
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus-data:/prometheus
+    networks: [monitoring]
+
+  grafana:
+    image: grafana/grafana:latest
+    volumes:
+      - grafana-data:/var/lib/grafana
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=secret
+    networks: [monitoring, proxy]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.grafana.rule=Host(`grafana.example.com`)"
+      - "traefik.http.services.grafana.loadbalancer.server.port=3000"
+
+  loki:
+    image: grafana/loki:latest
+    volumes:
+      - loki-data:/loki
+    networks: [monitoring]
+
+  promtail:
+    image: grafana/promtail:latest
+    volumes:
+      - /var/log/traefik:/var/log/traefik:ro
+      - ./promtail.yml:/etc/promtail/config.yml
+    networks: [monitoring]
+
+volumes:
+  prometheus-data:
+  grafana-data:
+  loki-data:
+
+networks:
+  monitoring:
+    internal: true
+```
+
+## Alerting Rules (Prometheus)
+
+```yaml
+groups:
+  - name: traefik
+    rules:
+      - alert: TraefikHighErrorRate
+        expr: |
+          sum(rate(traefik_service_requests_total{code=~"5.."}[5m]))
+          / sum(rate(traefik_service_requests_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High 5xx error rate ({{ $value | humanizePercentage }})"
+
+      - alert: TraefikHighLatency
+        expr: |
+          histogram_quantile(0.95,
+            sum(rate(traefik_service_request_duration_seconds_bucket[5m])) by (le, service)
+          ) > 2
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "P95 latency > 2s for {{ $labels.service }}"
+
+      - alert: TraefikDown
+        expr: up{job="traefik"} == 0
+        for: 1m
+        labels:
+          severity: critical
+
+      - alert: TraefikCertExpiringSoon
+        expr: (traefik_tls_certs_not_after - time()) / 86400 < 14
+        for: 1h
+        labels:
+          severity: warning
+        annotations:
+          summary: "TLS cert expires in {{ $value | humanize }} days"
+
+      - alert: TraefikHighOpenConnections
+        expr: traefik_entrypoint_open_connections > 1000
+        for: 5m
+        labels:
+          severity: warning
+
+      - alert: TraefikConfigReloadFailure
+        expr: traefik_config_last_reload_success == 0
+        for: 5m
+        labels:
+          severity: warning
+```
+
+## Health Check Endpoint
+
+```yaml
+# traefik.yml
+ping:
+  entryPoint: web
+  # OR separate entrypoint:
+  # entryPoint: ping
+```
+
+Check: `curl http://traefik:80/ping` returns `OK` with 200 status.
+
+Use for Kubernetes liveness/readiness probes:
+```yaml
+livenessProbe:
+  httpGet:
+    path: /ping
+    port: 80
+  initialDelaySeconds: 10
+  periodSeconds: 10
+readinessProbe:
+  httpGet:
+    path: /ping
+    port: 80
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+## Datadog Integration
+
+```yaml
+metrics:
+  datadog:
+    address: "datadog-agent:8125"
+    addEntryPointsLabels: true
+    addServicesLabels: true
+    prefix: traefik
+```
+
+## StatsD / InfluxDB
+
+```yaml
+# StatsD
+metrics:
+  statsD:
+    address: "statsd:8125"
+    addEntryPointsLabels: true
+    addServicesLabels: true
+
+# InfluxDB v2
+metrics:
+  influxDB2:
+    address: "http://influxdb:8086"
+    token: "your-token"
+    org: "your-org"
+    bucket: "traefik"
+    addEntryPointsLabels: true
+    addServicesLabels: true
+    pushInterval: 10s
+```
+
+## SLO/SLI Monitoring Patterns
+
+Define Service Level Indicators and Objectives:
+
+```yaml
+# Prometheus recording rules for SLIs
+groups:
+  - name: traefik-sli
+    rules:
+      # Availability SLI: % of non-5xx responses
+      - record: traefik:availability:ratio_rate5m
+        expr: |
+          1 - (
+            sum(rate(traefik_service_requests_total{code=~"5.."}[5m]))
+            / sum(rate(traefik_service_requests_total[5m]))
+          )
+
+      # Latency SLI: % of requests under 500ms
+      - record: traefik:latency_under_500ms:ratio_rate5m
+        expr: |
+          sum(rate(traefik_service_request_duration_seconds_bucket{le="0.5"}[5m]))
+          / sum(rate(traefik_service_request_duration_seconds_count[5m]))
+
+  - name: traefik-slo
+    rules:
+      # SLO burn rate alerts (multi-window)
+      - alert: TraefikAvailabilitySLOBreach
+        expr: traefik:availability:ratio_rate5m < 0.999
+        for: 10m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Availability SLO breach: {{ $value | humanizePercentage }} (target 99.9%)"
+
+      - alert: TraefikLatencySLOBreach
+        expr: traefik:latency_under_500ms:ratio_rate5m < 0.95
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Latency SLO breach: {{ $value | humanizePercentage }} under 500ms (target 95%)"
+```
+
+## OpenTelemetry Collector Config
+
+```yaml
+# otel-collector-config.yaml
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+processors:
+  batch:
+    timeout: 5s
+    send_batch_size: 1024
+
+exporters:
+  prometheus:
+    endpoint: 0.0.0.0:8889
+  otlp/jaeger:
+    endpoint: jaeger:4317
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [prometheus]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger]
+```