agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/flagger/SKILL.md

flagger

Skill4 starsChanged 5 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    progressDeadlineSeconds too low: If canary takes longer than this (e.g., image pull delay, slow startup), Flagger rolls back.

    line 290

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

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

FieldRequiredDescription
providerYesTraffic provider: kubernetes, istio, linkerd, nginx, contour, gloo, traefik, gatewayapi:v1, apisix, kuma, knative, skipper, osm, smi:v1alpha2, appmesh:v1beta2
targetRefYesTarget Deployment reference
autoscalerRefNoHPA reference (copied to canary)
serviceYesService spec (port, portName, targetPort, hosts, gatewayRefs, match, rewrite, timeout, headers, etc.)
suspendNoSuspend all canary runs
progressDeadlineSecondsNoMax time for canary progress before rollback (default 600)
skipAnalysisNoPromote without analysis (default false)

AnalysisSpec Fields

FieldRequiredDescription
intervalYesSchedule interval (e.g. 1m, 30s)
thresholdYesMax failed checks before rollback
maxWeightCanaryMax traffic % to canary (0-100). Used with stepWeight
stepWeightCanaryTraffic increment per interval (0-100). Used with maxWeight
stepWeightsCanaryExplicit array of traffic weights. Replaces stepWeight
stepWeightPromotionNoTraffic increment during promotion phase
iterationsA/B, Blue/GreenNumber of iterations (replaces stepWeight/maxWeight)
matchA/BHTTP header/cookie match conditions for A/B testing
mirrorBlue/GreenMirror traffic to canary (default false)
mirrorWeightNo% of traffic to mirror (0-100)
primaryReadyThresholdNo% of pods that must be available before starting (% , default 100)
canaryReadyThresholdNo% of canary pods that must be available (%, default 100)
metricsNoList of metric checks
webhooksNoList of webhooks (pre-rollout, rollout, confirm-promotion, etc.)
alertsNoList of alert configs
sessionAffinityNoSession affinity settings for canary

Analysis Strategies

StrategyFieldsTraffic shapingUse case
Canary (weighted)stepWeight + maxWeightGradual traffic shiftGradual rollout with metrics
Canary (custom steps)stepWeights: [5, 10, 25, 50, 75]Custom traffic stepsNon-linear rollout
A/B Testingiterations + matchHeader/cookie routingTest specific user segments
Blue/GreeniterationsInstant switchQuick rollback or pre-production validation
Blue/Green Mirroriterations + mirror: trueTraffic mirroringShadow traffic without impact

Metrics

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

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):

TypePhasePurpose
pre-rolloutBefore canary startsAcceptance tests, DB migrations check
confirm-rolloutBefore canary starts (gating)Manual approval gate
rolloutDuring analysis (each step)Load tests
confirm-promotionBefore promotion (gating)Manual approval for promotion
post-rolloutAfter promotionSmoke tests, cleanup
rollbackAfter rollbackCleanup, notifications
eventAny timeInformational events
confirm-traffic-increaseBefore each step increase (gating)Per-step manual approval

Alerts

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:

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

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)

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

ValueDefaultDescription
meshProvider"" (kubernetes)Traffic provider: istio, linkerd, nginx, contour, kubernetes, etc.
metricsServerhttp://prometheus.istio-system:9090Prometheus URL
logLevelinfoLog level
crd.createfalseCreate CRDs (Helm v3 handles this separately)
prometheus.installfalseInstall bundled Prometheus
prometheus.retention2hPrometheus data retention
serviceMonitor.enabledfalseCreate ServiceMonitor
podMonitor.enabledfalseCreate PodMonitor
namespace"" (all)Watch single namespace (empty = all)
selectorLabelsapp,name,app.kubernetes.io/nameLabels for workload selection

Provider-Specific Features

FeatureIstioLinkerdContourNGINXKubernetesGateway 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.