Flagger

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

AnalysisSpec Fields

Analysis Strategies

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

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

Provider-Specific Features

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.