k8s-agent-skills 1.2.0

package/skills/dragonfly/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: dragonfly
+description: Use when working with DragonflyDB operator on Kubernetes — creating or troubleshooting Dragonfly resources, configuring replication, snapshots, TLS, authentication, or affinity/scheduling for Dragonfly instances.
+---
+
+# DragonflyDB Operator
+
+## Overview
+
+Dragonfly operator manages Dragonfly (Redis-compatible) in-memory data store instances on Kubernetes. API: `dragonflydb.io/v1alpha1`. Single CRD: `Dragonfly` (plural: `dragonflies`). Deployed via Helm chart `oci://ghcr.io/dragonflydb/dragonfly-operator/helm/dragonfly-operator`. Latest operator: **v1.5.0** (Mar 2026). Deployed chart: v1.5.0.
+
+## CRD Fields
+
+| Field | Type | Since | Description |
+|-------|------|-------|-------------|
+| `replicas` | int | — | Total instances (1 = standalone primary, 2 = 1 primary + 1 replica) |
+| `image` | string | — | Dragonfly image (default: `docker.dragonflydb.io/dragonflydb/dragonfly:v1.21.2`) |
+| `args` | []string | — | Dragonfly server args (e.g. `--maxmemory=2gb`) |
+| `resources` | ResourceRequirements | — | Container CPU/memory |
+| `affinity` | Affinity | — | Pod affinity (nodeAffinity, podAntiAffinity, etc.) |
+| `nodeSelector` | map | v1.1.1 | Node selector for pod scheduling |
+| `tolerations` | []Toleration | — | Pod tolerations |
+| `topologySpreadConstraints` | []TopologySpreadConstraint | v1.1.1 | Spread pods across topology domains |
+| `annotations` | object | — | Annotations on Dragonfly pods |
+| `labels` | object | — | Labels on Dragonfly pods |
+| `env` | []EnvVar | — | Environment variables |
+| `authentication.passwordFromSecret` | SecretKeySelector | — | Password from Secret key |
+| `authentication.clientCaCertSecret` | SecretReference | — | Client CA certificate Secret |
+| `tlsSecretRef` | SecretReference | — | TLS cert Secret for server TLS |
+| `snapshot.cron` | string | — | Cron schedule for snapshots (e.g. `"\*/5 * * * *"`) |
+| `snapshot.persistentVolumeClaimSpec` | PVC Spec | — | PVC for snapshot storage |
+| `aclFromSecret` | SecretKeySelector | v1.1.1 | ACL file from Secret |
+| `serviceAccountName` | string | — | Pod service account |
+| `serviceSpec.type` | string | — | Service type (ClusterIP, LoadBalancer, etc.) |
+| `serviceSpec.name` | string | v1.1.3 | Custom service name |
+| `serviceSpec.annotations` | object | — | Service annotations |
+| `priorityClassName` | string | v1.1.1 | Pod priority class |
+| `skipFSGroup` | bool | v1.1.2 | Skip FSGroup assignment (OpenShift) |
+| `memcachedPort` | int | v1.1.2 | Memcached port (alternative to `--memcached_port` arg) |
+| `additionalContainers` | []Container | — | Sidecar containers |
+| `additionalVolumes` | []Volume | — | Extra volumes |
+
+## Dragonfly Spec Patterns
+
+```yaml
+apiVersion: dragonflydb.io/v1alpha1
+kind: Dragonfly
+metadata:
+  name: my-cache
+spec:
+  replicas: 1                    # 1 = standalone primary
+  args:
+    - --maxmemory=2gb
+    - --logtostderr
+    - --cluster_mode=emulated    # Enable cluster-compatible mode
+    - --lock_on_hashtags         # Hashtag-based locking
+    - --default_lua_flags=allow-undeclared-keys
+
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: "1"
+      memory: 2Gi
+
+  affinity:
+    nodeAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
+        nodeSelectorTerms:
+          - matchExpressions:
+              - key: kubernetes.io/hostname
+                operator: In
+                values:
+                  - worker-proxmox
+
+  authentication:
+    passwordFromSecret:
+      name: dragonfly-password
+      key: password
+
+  snapshot:
+    cron: "*/5 * * * *"
+    persistentVolumeClaimSpec:
+      accessModes:
+        - ReadWriteOnce
+      storageClassName: ceph-block
+      resources:
+        requests:
+          storage: 2Gi
+
+  serviceSpec:
+    type: ClusterIP
+    annotations:
+      external-dns.alpha.kubernetes.io/hostname: dragonfly.example.com
+```
+
+## Replication Model
+
+- `replicas=1` — standalone primary
+- `replicas=2` — 1 primary + 1 replica
+- `replicas=3` — 1 primary + 2 replicas
+- **Always exactly 1 primary** regardless of replica count
+- Operator manages automatic failover if primary fails
+- Service `<name>.<ns>.svc.cluster.local` always points to current primary
+
+## Authentication
+
+| Method | Config | Description |
+|--------|--------|-------------|
+| Password | `authentication.passwordFromSecret` | Basic password auth (maps to `--requirepass`) |
+| Client CA | `authentication.clientCaCertSecret` | TLS client cert verification |
+| ACL file | `aclFromSecret` | ACL rules file from Secret (v1.1.1+) |
+
+Password can also be set via `args: ["--requirepass=<pw>"]` or `env: [{name: DFLY_requirepass, value: "<pw>"}]`.
+
+## TLS
+
+```yaml
+spec:
+  tlsSecretRef:
+    name: dragonfly-tls    # Secret must have tls.crt, tls.key
+```
+
+Secret must exist in same namespace. Optionally combine with `authentication.clientCaCertSecret` for mutual TLS.
+
+## Snapshots
+
+Snapshots store Dragonfly data to PVC for persistence across restarts:
+
+```yaml
+spec:
+  snapshot:
+    cron: "*/5 * * * *"
+    persistentVolumeClaimSpec:
+      storageClassName: ceph-block
+      accessModes: [ReadWriteOnce]
+      resources:
+        requests:
+          storage: 2Gi
+```
+
+- `cron` is optional — omit for on-demand only
+- Snapshots **not auto-pruned** — manage disk or use static `--dbfilename` to overwrite
+- PVC spec follows standard Kubernetes `PersistentVolumeClaimSpec`
+
+## Exposing Dragonfly as Cache
+
+Applications connect via the service at `<name>.<ns>.svc.cluster.local:6379`. In apps using Dragonfly as Redis-compatible cache (valkey/Redis clients):
+
+```yaml
+# In the app's ConfigMap or env
+REDIS_URL: redis://:${REDIS_PASSWORD}@my-cache.namespace:6379
+REDIS_PASSWORD: # from Dragonfly auth secret
+```
+
+For cluster-mode emulated (`--cluster_mode=emulated`), Redis cluster clients (e.g. `ioredis` cluster mode) can connect as if it's a Redis Cluster — but there's only one actual Dragonfly instance behind the service.
+
+## Monitoring
+
+Dragonfly exposes metrics on the `admin` port. Use a `PodMonitor` to scrape:
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: PodMonitor
+metadata:
+  name: dragonfly-monitor
+spec:
+  selector:
+    matchLabels:
+      app: my-cache               # Must match Dragonfly resource name
+  podMetricsEndpoints:
+    - port: admin
+```
+
+The operator creates pods with label `app: <dragonfly-name>` by default.
+
+## Common Mistakes
+
+- **`replicas` confusion** — replicas=2 means 1 primary + 1 replica, NOT 2 primaries
+- **No snapshot cron** — without `cron` + PVC, restarts lose all data; always configure for stateful use
+- **`cluster_mode=emulated` without `lock_on_hashtags`** — emulated cluster needs hashtag locking for multi-key ops
+- **Password collision** — don't set password via both `authentication.passwordFromSecret` AND `--requirepass` arg; use the CRD field
+- **Same storageClass for all** — immich with ceph-block fine; if latency-sensitive, use local SSD via `nodeSelector` + local storage
+- **No resource limits** — Dragonfly can OOM under load; always set `resources.limits.memory`
+- **Helm chart OCI URL** — use `oci://ghcr.io/dragonflydb/dragonfly-operator/helm`, chart name `dragonfly-operator`, version `v1.5.0`
+
+## Version History
+
+| Operator | Helm Chart | Date | Notes |
+|----------|-----------|------|-------|
+| v1.5.0 | v1.5.0 | Mar 2026 | Latest (deployed) |
+| v1.4.0 | v1.4.0 | Jan 2026 | |
+| v1.3.1 | v1.3.1 | Nov 2025 | |

package/skills/external-dns/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: external-dns
+description: Use when working with ExternalDNS — synchronizing Kubernetes resources with DNS providers (Cloudflare). Covers providers, sources, registry, RBAC, Gateway API integration, Helm values. No CRDs.
+---
+
+# ExternalDNS
+
+## Overview
+
+ExternalDNS synchronizes exposed Kubernetes Services, Ingresses, and Gateway API routes with DNS providers. It watches resources via the K8s watch API and creates/updates/deletes DNS records to match.
+
+**No CRDs.** Controlled via CLI flags, sources, and provider-specific config.
+
+**Latest:** chart 1.21.1, app v0.21.0.
+
+## Architecture
+
+```
+K8s Sources (Ingress, HTTPRoute, Service...)
+  → ExternalDNS watches for changes
+    → Resolves to DNS endpoints
+      → Creates/updates/deletes DNS records (Cloudflare, Route53, etc.)
+        → Registry (TXT records) tracks ownership
+```
+
+## Sources
+
+ExternalDNS queries one or more source types for DNS endpoints:
+
+| Source | Flag | Supported |
+|--------|------|-----------|
+| Ingress | `--source=ingress` | ✅ |
+| Service (LoadBalancer) | `--source=service` | ✅ (no NodePort) |
+| Gateway HTTPRoute | `--source=gateway-httproute` | ✅ |
+| Gateway GRPCRoute | `--source=gateway-grpcroute` | ✅ |
+| Gateway TLSRoute | `--source=gateway-tlsroute` | ✅ (v1alpha2) |
+| Gateway TCPRoute | `--source=gateway-tcproute` | ✅ (experimental) |
+| Gateway UDPRoute | `--source=gateway-udproute` | ✅ (experimental) |
+| Istio Gateway | `--source=istio-gateway` | ✅ |
+| Istio VirtualService | `--source=istio-virtualservice` | ✅ |
+| CRD | `--source=crd` | ✅ (externaldns.k8s.io/v1alpha1) |
+| Node | `--source=node` | ✅ |
+| Pod | `--source=pod` | ✅ |
+| OpenShift Route | `--source=openshift-route` | ✅ |
+| Contour HTTPProxy | `--source=contour-httpproxy` | ✅ |
+| Traefik Proxy | `--source=traefik-proxy` | ✅ |
+
+**Deployed sources:** `ingress`, `gateway-httproute`.
+
+## Providers
+
+ExternalDNS supports 25+ providers. Deployed: Cloudflare.
+
+### Cloudflare
+
+Auth via API token (env var `CF_API_TOKEN`). Example values:
+
+```yaml
+provider:
+  name: cloudflare
+env:
+  - name: CF_API_TOKEN
+    valueFrom:
+      secretKeyRef:
+        name: cloudflare-credentials
+        key: api-token
+extraArgs:
+  - --cloudflare-proxied
+```
+
+Cloudflare-specific flags:
+
+| Flag | Description |
+|------|-------------|
+| `--cloudflare-proxied` | Enable Cloudflare proxy (orange cloud) — CDN, DDoS protection, SSL |
+| `--cloudflare-dns-records-per-page=N` | Records per page (default 100, max 5000) |
+| `--cloudflare-custom-hostnames` | Enable Cloudflare for SaaS Custom Hostnames |
+| `--cloudflare-regional-services` | Restrict HTTPS decryption to specific regions |
+| `--cloudflare-region-key` | Region key for regional services |
+| `--cloudflare-record-comment` | Add comment to provisioned records (≤100/≤500 chars) |
+
+## Registry & Policy
+
+Controls how ExternalDNS tracks ownership of records:
+
+```yaml
+registry: txt          # Use TXT records to track ownership
+txtOwnerId: my-cluster # Owner identifier in TXT record
+policy: upsert-only    # Only create/update, never delete
+```
+
+| Registry | Description |
+|----------|-------------|
+| `txt` | TXT records with owner ID (prevents overwriting records from other sources) |
+| `aws` | AWS Route53 tag-based (provider-specific) |
+| `noop` | No ownership tracking |
+
+| Policy | Description |
+|--------|-------------|
+| `upsert-only` | Create and update only (safe for shared zones) |
+| `sync` | Full sync — create, update, delete (can delete external records) |
+| `create-only` | Only create, never update or delete |
+
+## Domain & Ownership Filtering
+
+```yaml
+domainFilters:
+  - example.com        # Only manage records in this zone
+excludeDomains: []     # Exclude specific domains
+zoneIdFilters: []      # Limit to specific zone IDs
+annotationFilter: ""   # Filter resources by annotation
+labelFilter: ""        # Filter resources by label
+```
+
+## Gateway API Integration
+
+ExternalDNS reads hostnames from Gateway API HTTPRoute/GRPCRoute resources:
+
+```yaml
+sources:
+  - gateway-httproute
+  - gateway-grpcroute
+```
+
+RBAC for Gateway sources requires additional permissions:
+
+```yaml
+rbac:
+  extraRules:
+    - apiGroups: ["gateway.networking.k8s.io"]
+      resources: ["httproutes", "gateways"]
+      verbs: ["get", "watch", "list"]
+```
+
+HTTPRoute annotations for per-route overrides:
+
+```yaml
+metadata:
+  annotations:
+    external-dns.alpha.kubernetes.io/cloudflare-proxied: "true"
+    external-dns.alpha.kubernetes.io/ttl: "300"
+```
+
+## Deployment (Flux HelmRelease)
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+spec:
+  chart:
+    spec:
+      chart: external-dns
+      sourceRef:
+        kind: HelmRepository
+        name: external-dns
+      version: 1.21.1
+```
+
+### Helm Values
+
+| Value | Default | Description |
+|-------|---------|-------------|
+| `provider.name` | `aws` | DNS provider (cloudflare, google, aws, azure, etc.) |
+| `sources` | `[service, ingress]` | Resources to watch (ingress, gateway-httproute, service, etc.) |
+| `domainFilters` | `[]` | Limit to specific DNS zones |
+| `policy` | `upsert-only` | Sync policy (upsert-only, sync, create-only) |
+| `registry` | `txt` | Ownership registry (txt, aws, noop) |
+| `txtOwnerId` | — | Owner identifier for TXT registry |
+| `interval` | `1m` | Sync interval |
+| `logLevel` | `info` | Log verbosity |
+| `rbac.create` | `true` | Create ClusterRole |
+| `rbac.extraRules` | `[]` | Additional RBAC rules (e.g. for Gateway API) |
+| `nodeSelector` | `{}` | Node selector |
+| `tolerations` | `[]` | Pod tolerations |
+| `extraArgs` | `[]` | Additional CLI args |
+
+## Common Mistakes
+
+- **Missing RBAC for Gateway sources.** Without `rbac.extraRules`, gateway-httproute source returns no endpoints. Both `httproutes` and `gateways` resources must be listed.
+- **`upsert-only` doesn't clean up stale records.** When an Ingress/HTTPRoute is deleted, its DNS record persists. Use `sync` policy or manual cleanup.
+- **Cloudflare API token needs specific permissions.** Requires `Zone:DNS:Edit` for the target zone. A token with only `Zone:Read` will fail silently.
+- **`--cloudflare-proxied` is a global flag.** To proxy only specific records, omit the global flag and use the `external-dns.alpha.kubernetes.io/cloudflare-proxied: "true"` annotation per resource.
+- **Domain filter is a suffix match.** `kubexa.tech` matches `app.kubexa.tech` but NOT `kubexa.tech.app.com`. Add trailing dot if needed.
+- **NodePort services not supported** with `source=service`. Only LoadBalancer services are detected.
+- **Multiple TXT owner IDs on same zone.** If two ExternalDNS instances manage the same zone with different `txtOwnerId`, they can coexist. Records with unknown owner ID are left untouched by `upsert-only`.

package/skills/flagger/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: flagger
+description: Use when working with Flagger — progressive delivery, canary deployments, A/B testing, blue/green on Kubernetes. Covers Canary CRD, analysis/meshes/metrics/webhooks, Helm values. CRDs: Canary, MetricTemplate, AlertProvider.
+---
+
+# Flagger
+
+## Overview
+
+Flagger automates progressive delivery for Kubernetes workloads. It gradually shifts traffic to a new version while measuring metrics and running conformance tests. Supports canary releases (weighted traffic), A/B testing (header/cookie routing), and blue/green deployments (instant switch or mirroring).
+
+**CRDs:** `Canary` (flagger.app/v1beta1), `MetricTemplate`, `AlertProvider`.
+
+**Latest:** chart 1.43.0, app v1.43.0 (Apr 2026).
+
+## Architecture
+
+```
+User creates/updates Canary resource
+  → Flagger creates:
+    - <name>-primary Deployment (stable version)
+    - <name>-canary Deployment (new version)
+    - <name> ClusterIP service (routes to primary)
+    - <name>-primary ClusterIP service (stable)
+    - <name>-canary ClusterIP service (new)
+    - Mesh/Ingress routing objects (if mesh provider set)
+  → Analysis loop:
+    1. Increment traffic to canary (stepWeight)
+    2. Run webhooks (pre-rollout, rollout, post-rollout)
+    3. Check metrics (success rate, duration, custom)
+    4. If all pass → promote canary to primary
+    5. If threshold exceeded → rollback
+```
+
+## CRD: Canary
+
+`apiVersion: flagger.app/v1beta1`, `kind: Canary`
+
+### Minimal Example (Kubernetes CNI — no mesh)
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+  name: myapp
+  namespace: prod
+spec:
+  provider: kubernetes    # No service mesh (uses ClusterIP + pod labels)
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: myapp
+  service:
+    port: 9898
+    portDiscovery: true
+  analysis:
+    interval: 1m
+    threshold: 5
+    iterations: 10        # Used for blue/green with no mesh provider
+    metrics:
+      - name: request-success-rate
+        thresholdRange:
+          min: 99
+        interval: 1m
+    webhooks:
+      - name: load-test
+        type: rollout
+        url: http://flagger-loadtester.test/
+        metadata:
+          cmd: "hey -z 1m -q 10 http://myapp-canary.prod:9898/"
+```
+
+### CanarySpec Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `provider` | Yes | Traffic provider: `kubernetes`, `istio`, `linkerd`, `nginx`, `contour`, `gloo`, `traefik`, `gatewayapi:v1`, `apisix`, `kuma`, `knative`, `skipper`, `osm`, `smi:v1alpha2`, `appmesh:v1beta2` |
+| `targetRef` | Yes | Target Deployment reference |
+| `autoscalerRef` | No | HPA reference (copied to canary) |
+| `service` | Yes | Service spec (port, portName, targetPort, hosts, gatewayRefs, match, rewrite, timeout, headers, etc.) |
+| `suspend` | No | Suspend all canary runs |
+| `progressDeadlineSeconds` | No | Max time for canary progress before rollback (default 600) |
+| `skipAnalysis` | No | Promote without analysis (default false) |
+
+### AnalysisSpec Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `interval` | Yes | Schedule interval (e.g. `1m`, `30s`) |
+| `threshold` | Yes | Max failed checks before rollback |
+| `maxWeight` | Canary | Max traffic % to canary (0-100). Used with `stepWeight` |
+| `stepWeight` | Canary | Traffic increment per interval (0-100). Used with `maxWeight` |
+| `stepWeights` | Canary | Explicit array of traffic weights. Replaces stepWeight |
+| `stepWeightPromotion` | No | Traffic increment during promotion phase |
+| `iterations` | A/B, Blue/Green | Number of iterations (replaces stepWeight/maxWeight) |
+| `match` | A/B | HTTP header/cookie match conditions for A/B testing |
+| `mirror` | Blue/Green | Mirror traffic to canary (default false) |
+| `mirrorWeight` | No | % of traffic to mirror (0-100) |
+| `primaryReadyThreshold` | No | % of pods that must be available before starting (% , default 100) |
+| `canaryReadyThreshold` | No | % of canary pods that must be available (%, default 100) |
+| `metrics` | No | List of metric checks |
+| `webhooks` | No | List of webhooks (pre-rollout, rollout, confirm-promotion, etc.) |
+| `alerts` | No | List of alert configs |
+| `sessionAffinity` | No | Session affinity settings for canary |
+
+### Analysis Strategies
+
+| Strategy | Fields | Traffic shaping | Use case |
+|----------|--------|-----------------|----------|
+| Canary (weighted) | `stepWeight` + `maxWeight` | Gradual traffic shift | Gradual rollout with metrics |
+| Canary (custom steps) | `stepWeights: [5, 10, 25, 50, 75]` | Custom traffic steps | Non-linear rollout |
+| A/B Testing | `iterations` + `match` | Header/cookie routing | Test specific user segments |
+| Blue/Green | `iterations` | Instant switch | Quick rollback or pre-production validation |
+| Blue/Green Mirror | `iterations` + `mirror: true` | Traffic mirroring | Shadow traffic without impact |
+
+### Metrics
+
+```yaml
+metrics:
+  - name: request-success-rate
+    thresholdRange:
+      min: 99
+    interval: 1m
+  - name: request-duration
+    thresholdRange:
+      max: 500
+    interval: 30s
+  - name: custom-metric
+    templateRef:
+      name: my-metric-template
+      namespace: flagger
+    thresholdRange:
+      min: 2
+      max: 100
+    interval: 1m
+```
+
+Built-in metric checks (when `templateRef` is not set):
+- `request-success-rate` — Prometheus query `rate(...)` for non-5xx responses
+- `request-duration` — Prometheus query `histogram_quantile(0.99, ...)` for P99 latency
+
+Custom metrics use `MetricTemplate` CRD (see below).
+
+### Webhooks
+
+```yaml
+webhooks:
+  - name: "load test"
+    type: rollout              # Run during canary analysis
+    url: http://tester/        # Webhook endpoint
+    timeout: 5m
+    retries: 3
+    disableTLS: false
+    metadata:
+      cmd: "hey -z 1m http://app:9898/"
+```
+
+Webhook types (execution order):
+
+| Type | Phase | Purpose |
+|------|-------|---------|
+| `pre-rollout` | Before canary starts | Acceptance tests, DB migrations check |
+| `confirm-rollout` | Before canary starts (gating) | Manual approval gate |
+| `rollout` | During analysis (each step) | Load tests |
+| `confirm-promotion` | Before promotion (gating) | Manual approval for promotion |
+| `post-rollout` | After promotion | Smoke tests, cleanup |
+| `rollback` | After rollback | Cleanup, notifications |
+| `event` | Any time | Informational events |
+| `confirm-traffic-increase` | Before each step increase (gating) | Per-step manual approval |
+
+### Alerts
+
+```yaml
+alerts:
+  - name: "Slack"
+    severity: error       # info, warn, error
+    providerRef:
+      name: dev-slack
+      namespace: flagger
+```
+
+## CRD: MetricTemplate
+
+`apiVersion: flagger.app/v1beta1`, `kind: MetricTemplate`
+
+Defines custom metric queries for canary analysis:
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: MetricTemplate
+metadata:
+  name: db-connections
+  namespace: flagger
+spec:
+  provider:
+    type: prometheus
+    address: http://prometheus.monitoring:9090
+  query: |
+    avg_over_time(
+      pg_stat_activity_count{namespace="{{ namespace }}",app="{{ target }}"}[{{ interval }}]
+    )
+```
+
+Template variables: `{{ namespace }}`, `{{ target }}`, `{{ interval }}`.
+
+## CRD: AlertProvider
+
+`apiVersion: flagger.app/v1beta1`, `kind: AlertProvider`
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: AlertProvider
+metadata:
+  name: dev-slack
+  namespace: flagger
+spec:
+  type: slack
+  channel: flagger-alerts
+  username: flager
+  address: https://hooks.slack.com/services/TOKEN
+```
+
+Supported types: `slack`, `teams`, `discord`, `rocket`.
+
+## Deployment (Flux HelmRelease)
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: flagger
+  namespace: flagger-system
+spec:
+  interval: 24h
+  url: https://flagger.app
+---
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: flagger
+  namespace: flagger-system
+spec:
+  chart:
+    spec:
+      chart: flagger
+      sourceRef:
+        kind: HelmRepository
+        name: flagger
+      version: "1.39.0"
+  values:
+    meshProvider: ""                # Kubernetes CNI mode
+    metricsServer: "http://prometheus:9090"
+    prometheus:
+      install: false                # Use existing Prometheus
+```
+
+## Helm Values
+
+| Value | Default | Description |
+|-------|---------|-------------|
+| `meshProvider` | `""` (kubernetes) | Traffic provider: istio, linkerd, nginx, contour, kubernetes, etc. |
+| `metricsServer` | `http://prometheus.istio-system:9090` | Prometheus URL |
+| `logLevel` | `info` | Log level |
+| `crd.create` | `false` | Create CRDs (Helm v3 handles this separately) |
+| `prometheus.install` | `false` | Install bundled Prometheus |
+| `prometheus.retention` | `2h` | Prometheus data retention |
+| `serviceMonitor.enabled` | `false` | Create ServiceMonitor |
+| `podMonitor.enabled` | `false` | Create PodMonitor |
+| `namespace` | `""` (all) | Watch single namespace (empty = all) |
+| `selectorLabels` | `app,name,app.kubernetes.io/name` | Labels for workload selection |
+
+## Provider-Specific Features
+
+| Feature | Istio | Linkerd | Contour | NGINX | Kubernetes | Gateway API |
+|---------|-------|---------|---------|-------|-----------|-------------|
+| Weighted canary | ✅ | ✅ | ✅ | ✅ | ➖ | ✅ |
+| A/B testing | ✅ | ➖ | ✅ | ✅ | ➖ | ✅ |
+| Blue/green (switch) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Blue/green (mirror) | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ |
+| Request success rate | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ |
+| Request duration | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ |
+
+## Common Mistakes
+
+- **`meshProvider: ""` (Kubernetes CNI) has no traffic shaping.** Flagger can only do blue/green (iterations-based) with the `kubernetes` provider. Weighted canary (stepWeight) requires a service mesh or ingress controller.
+- **Prometheus must be reachable.** Without `metricsServer`, the analysis loop immediately fails. Verify Prometheus URL and that Flagger can query it.
+- **CRDs not installed.** `crd.create: false` means CRDs must be installed separately. If running Flux, the CRDs from the upstream `crds.yaml` must exist before Canary resources are applied.
+- **Webhook URL must be reachable from Flagger pod.** Load test webhooks are called during canary analysis. If the webhook times out or returns error, the canary fails. Use cluster-internal URLs.
+- **`targetRef` must be a Deployment.** Flagger only supports Deployment as the target. Other workload types (StatefulSet, DaemonSet) won't work.
+- **`progressDeadlineSeconds` too low.** If canary takes longer than this (e.g., image pull delay, slow startup), Flagger rolls back. Default 600s. Increase for large images.
+- **Missing `service.port`.** Required field. Flagger creates ClusterIP services and needs to know the container port.
+- **Metric template `{{ target }}` defaults to the canary name.** In Prometheus queries, `{{ target }}` resolves to the service name. Ensure your metrics service matches the label selectors Flagger sets.