Les APIs essentielles pour les canary deploys

Un canary sans API de décision ne décide rien. Les quatre couches à brancher, les endpoints qui comptent et les pièges de cardinalité qui font annuler un rollout.

Les APIs essentielles pour les canary deploys

Un canary qui ne parle à aucune API de décision, c'est un déploiement à 5 % que personne ne regarde. J'ai vu la différence sur une API de facturation : 5 % du trafic pendant douze minutes, zéro erreur 500, et un p95 qui passait de 120 à 410 ms sans qu'aucune alerte ne bronche. Le rollout a été promu « parce que ça avait l'air calme ».

Ce qui sépare un canary utile d'un canary décoratif tient à quatre appels HTTP : un qui change le poids du trafic, un qui lit les métriques, un qui compare au baseline, un qui promeut ou annule. Voici les APIs qui font ce travail, avec les endpoints, les payloads et les limites que j'ai réellement rencontrées.

Pourquoi un canary sans métriques ne décide rien

Un canary sert à réduire le rayon d'explosion, pas à éviter l'incident. Si ton seul signal est le taux d'erreur HTTP, tu ne détectes que les pannes franches. Les régressions de latence, les fuites mémoire et les erreurs métier silencieuses passent toutes sous le radar.

Concrètement, une régression de 3× sur le p95 avec 0,2 % d'erreurs ne déclenche rien si ton gate compare seulement les 5xx. Il te faut donc un gate qui compare un candidat à une référence, sur plusieurs signaux, avec un seuil chiffré. C'est de l'ingénierie, pas de la supervision passive.

Les quatre couches d'API à brancher

CoucheRôleAPI typiqueOù ça casse
OrchestrationLancer une seconde version à côté de la premièreKubernetes API, CRD Rollout, Docker APIDeux Deployments qui se battent sur le même label selector
TraficRouter x % vers le candidatGateway API HTTPRoute, Istio VirtualService, Traefik, annotations NGINXPoids appliqué côté client DNS, jamais côté proxy
MesureLire les signaux du candidat et du stablePrometheus /api/v1/query, OTLP, DatadogLabels absents : impossible de séparer canary et stable
DécisionPromouvoir, prolonger ou annulerAnalysisRun, webhooks Flagger, CI/CDGate qui passe sur une division 0/0

La couche qui manque le plus souvent est la dernière. Beaucoup d'équipes automatisent le routage et laissent la décision à un humain devant Grafana. Résultat : le canary dure trois jours, puis on le désactive parce qu'il « ralentit les releases ».

Orchestration : Kubernetes et les CRD de rollout

Le Deployment natif de Kubernetes fait du rolling update, pas du canary avec analyse. Il te donne maxSurge et maxUnavailable, c'est tout. Pour un vrai canary, tu as deux options sérieuses : Argo Rollouts ou Flagger, tous deux basés sur des CRD.

Les deux s'installent comme des contrôleurs et exposent une API REST derrière leurs propres ressources. Tu peux les piloter en kubectl ou en HTTP direct, ce qui compte quand ton pipeline n'est pas dans le cluster :

# promouvoir immédiatement le canary en cours
kubectl argo rollouts promote api-facturation -n prod

# annuler et revenir au stable
kubectl argo rollouts abort api-facturation -n prod

# équivalent HTTP : lecture de l'état du rollout
curl -s --cacert ~/.kube/ca.crt \
  -H "Authorization: Bearer $TOKEN" \
  "https://k8s.prod:6443/apis/argoproj.io/v1alpha1/namespaces/prod/rollouts/api-facturation" \
  | jq '.status.canary.currentStepIndex, .status.canary.stableRS'

Un détail qui m'a coûté une soirée : abort et undo ne font pas la même chose. undo revient au ReplicaSet précédent en repassant par les étapes, abort coupe le canary immédiatement et laisse le stable à 100 %. Sur un incident, c'est abort qu'il faut.

Argo Rollouts : le CRD qui porte la décision

Argo Rollouts place l'analyse dans la définition du rollout. Tu déclares des étapes, et chaque étape peut déclencher une AnalysisRun qui interroge Prometheus. La documentation Argo Rollouts couvre bien le sujet, voici la version minimale qui tourne chez moi :

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: api-facturation
spec:
  replicas: 8
  strategy:
    canary:
      canaryService: api-facturation-canary
      stableService: api-facturation-stable
      trafficRouting:
        traefik:
          weightedTraefikServiceName: api-facturation-wrr
      analysis:
        templates:
          - templateName: latence-et-erreurs
        startingStep: 1
        args:
          - name: service
            value: api-facturation
      steps:
        - setWeight: 10
        - pause: {duration: 5m}
        - setWeight: 30
        - pause: {duration: 10m}
        - setWeight: 60
        - pause: {duration: 10m}
---
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: latence-et-erreurs
spec:
  args:
    - name: service
  metrics:
    - name: taux-erreur
      interval: 1m
      count: 5
      failureLimit: 1
      successCondition: result[0] < 0.005
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: |
            sum(rate(http_requests_total{service="{{args.service}}",canary="true",code=~"5.."}[2m]))
            /
            sum(rate(http_requests_total{service="{{args.service}}",canary="true"}[2m]))
    - name: p95
      interval: 1m
      count: 5
      failureLimit: 1
      successCondition: result[0] < 0.35
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: |
            histogram_quantile(0.95,
              sum(rate(http_request_duration_seconds_bucket{service="{{args.service}}",canary="true"}[2m])) by (le))

Le point important est failureLimit: 1 avec count: 5 : une seule mesure hors seuil annule, mais il faut cinq mesures pour valider. Sans ce réglage, un pic de 30 secondes suffit à faire échouer un rollout sain.

L'état de chaque analyse est lisible par API, ce qui te permet de brancher Slack ou ton pipeline sans scraper des logs :

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://k8s.prod:6443/apis/argoproj.io/v1alpha1/namespaces/prod/analysisruns?labelSelector=rollout=api-facturation" \
  | jq -r '.items[] | "\(.metadata.name) \(.status.phase) \(.status.metricResults[].measurements[-1].value)"'

Flagger : l'API de vérification par webhooks

Flagger prend l'angle inverse. Tu ne décris pas les étapes, tu décris le rythme et les seuils, et Flagger calcule la montée en charge tout seul. Sa force est le système de webhooks : chargement synthétique avant promotion, tests d'acceptation, notification.

apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: api-facturation
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-facturation
  service:
    port: 8080
    gateways:
      - public-gateway.istio-system.svc.cluster.local
  analysis:
    interval: 1m
    threshold: 3
    maxWeight: 50
    stepWeight: 10
    metrics:
      - name: error-rate
        thresholdRange: {max: 1}
        interval: 1m
        templateRef:
          name: error-rate
          namespace: istio-system
    webhooks:
      - name: charge-realiste
        type: pre-rollout
        url: http://k6-runner.test:8080/run
        timeout: 5m
      - name: tests-acceptation
        type: rollout
        url: http://smoke.test:8080/canary
        timeout: 60s

threshold: 3 signifie trois échecs consécutifs avant rollback, pas trois échecs au total. C'est la confusion la plus fréquente quand on relit une config Flagger. La doc Flagger le précise, mais le nom du champ n'aide pas.

CritèreArgo RolloutsFlagger
ModèleÉtapes déclaratives + AnalysisRunMontée automatique par paliers
TraficTraefik, NGINX, Istio, Gateway API, ALBIstio, Linkerd, App Mesh, Gateway API, NGINX
Décision externeWebhooks pre/post sur le RolloutWebhooks natifs à 5 points du cycle
Test de charge intégréNonOui, via loadtester
Courbe d'apprentissageMoyenne, le YAML est verbeuxPlus douce pour un canary standard

Mon avis : Argo Rollouts si tu veux contrôler précisément les paliers et les métriques par étape, Flagger si tu veux un canary qui se débrouille seul avec des tests de charge. Les deux sont bons, le pire choix est de réécrire un contrôleur maison.

Le trafic sans Kubernetes : Gateway API, Traefik, NGINX

Un canary n'a pas besoin de Kubernetes. Ce dont tu as besoin, c'est une API qui accepte un poids de trafic modifiable à chaud. La Gateway API est le standard le plus propre aujourd'hui :

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-facturation
spec:
  parentRefs:
    - name: public-gateway
  rules:
    - matches:
        - path: {type: PathPrefix, value: /v1}
      backendRefs:
        - name: api-facturation-stable
          port: 8080
          weight: 90
        - name: api-facturation-canary
          port: 8080
          weight: 10

Basculer de 10 % à 25 % devient un simple patch JSON, sans redéploiement :

curl -s -X PATCH \
  --cacert ~/.kube/ca.crt -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  "https://k8s.prod:6443/apis/gateway.networking.k8s.io/v1/namespaces/prod/httproutes/api-facturation" \
  -d '{"spec":{"rules":[{"matches":[{"path":{"type":"PathPrefix","value":"/v1"}}],
       "backendRefs":[
         {"name":"api-facturation-stable","port":8080,"weight":75},
         {"name":"api-facturation-canary","port":8080,"weight":25}]}]}}'

Sous Traefik, l'équivalent est un TraefikService en weighted, et l'API accepte la même logique de patch. Sous NGINX, tu retombes sur des annotations (nginx.ingress.kubernetes.io/canary-weight) qui ne permettent qu'un canary par Ingress. C'est suffisant pour un premier palier, insuffisant pour une progression par étapes.

Prometheus : l'API qui compare vraiment

C'est la pièce que les tutos survolent. Un gate canary, ce n'est pas une alerte Prometheus : c'est une requête instantanée comparée à une valeur attendue. Endpoint utile : GET /api/v1/query?query=..., pas query_range.

import requests

PROM = "http://prometheus.monitoring:9090/api/v1/query"

def taux_erreur(service: str, canary: bool) -> float:
    q = ('sum(rate(http_requests_total{service="%s",canary="%s",code=~"5.."}[3m]))'
         ' / sum(rate(http_requests_total{service="%s",canary="%s"}[3m]))'
         % (service, str(canary).lower(), service, str(canary).lower()))
    r = requests.get(PROM, params={"query": q}, timeout=10).json()
    result = r["data"]["result"]
    if not result:
        raise RuntimeError("serie vide — le label canary est peut-etre absent")
    return float(result[0]["value"][1])

stable = taux_erreur("api-facturation", canary=False)
candidat = taux_erreur("api-facturation", canary=True)

# on ne compare pas a un seuil absolu mais au stable, avec une marge
if candidat > max(stable * 1.5, 0.005):
    abort_rollout("api-facturation")
else:
    promote_rollout("api-facturation")

Deux règles que j'applique systématiquement. Première : comparer canary et stable au même instant, jamais au même service hier — la charge, le cache et le trafic changent. Deuxième : refuser la promotion quand le dénominateur est trop faible. Une requête sur 200 donne un taux d'erreur de 0,5 % qui ne veut rien dire, et une division par zéro renvoie NaN, que beaucoup de gates interprètent comme « conforme ».

La doc Prometheus détaille les fonctions de requête, et c'est rate() sur une fenêtre d'au moins 4× le scrape interval qu'il faut utiliser. Avec un scrape à 15 s, une fenêtre de 30 s te donne deux points, donc du bruit pur.

Feature flags : l'autre API de canary

Le canary de trafic mesure l'infrastructure. Il ne dit rien de la conversion, du panier moyen ou du taux d'erreur métier. Pour ça, il faut une API d'évaluation de flags, et le standard du moment est OpenFeature.

L'intérêt d'OpenFeature est le découplage : tu écris une évaluation, tu changes de fournisseur (flagd, LaunchDarkly, Flagsmith, Unleash) sans toucher au code métier. Le contexte d'évaluation porte l'identité, et le pourcentage se règle côté service de flags :

from openfeature import api
from openfeature.provider.flagd import FlagdProvider

api.set_provider(FlagdProvider(host="flagd.flags.svc", port=8013))
client = api.get_client("facturation")

ctx = api.EvaluationContext(targeting_key=user.id, attributes={"plan": user.plan})
nouveau_calcul = client.get_boolean_value("facturation.v2", False, ctx)

Différence de nature avec le canary de trafic : ici, deux utilisateurs dans la même requête peuvent voir deux comportements. Ce n'est pas une infra qui bascule, c'est une population qui bascule. Les deux se complètent, ils ne se remplacent pas.

L'API de verdict : la partie que tout le monde oublie

Avant d'écrire une ligne de YAML, fixe tes seuils. Un canary sans seuils chiffrés se termine toujours par « on verra demain ». Voici les gates que j'utilise sur une API à 400 req/s :

SignalSeuil d'annulationFenêtre
Taux de 5xx> 1,5× le stable, plancher 0,5 %3 min
Latence p95> 300 ms ou > 1,3× le stable5 min
Redémarrages de pods≥ 1 sur le ReplicaSet canarydurée du rollout
Saturation CPU> 85 % pendant 3 relevés3 min
Erreur métierconversion en baisse de 10 %1 h

Le soak compte autant que le pic. Un canary de 2 minutes attrape les crash loops, pas les fuites mémoire ni les connexions non libérées. Chez moi, le palier final reste à 30 % pendant 10 minutes, ce qui suffit à faire apparaître une fuite de descripteurs.

Et prévois l'annulation automatique en cas de silence. Si le contrôleur ne reçoit plus de métriques (Prometheus indisponible, label renommé), le gate doit annuler, pas promouvoir par défaut. C'est le bug le plus vicieux du lot : ton rollout le plus risqué est celui qui passe quand l'observabilité est tombée.

Les pièges que j'ai payés

  • Cardinalité. Ajouter un label canary sur toutes les métriques HTTP a doublé le nombre de séries. Sur 200 pods, c'est 40 000 séries en plus. Règle : garder service, code, canary et enregistrer le reste en recording rules.
  • Fenêtre trop courte. Une fenêtre [1m] avec un scrape à 30 s donne deux échantillons. Le taux d'erreur saute de 0 à 8 % d'un relevé à l'autre sans que rien ne change.
  • Baseline absent. Comparer à un seuil fixe de 1 % fonctionne jusqu'au jour où ton trafic double. La comparaison stable/canary simultanée est la seule qui tienne.
  • Webhook lent. Un hook de test d'acceptation à 90 s avec un timeout de 60 s bloque le rollout, puis le marque en échec sans explication claire. Mets le timeout au-dessus du p99 du hook, pas en dessous.
  • Pause infinie. Un pause: {} sans durée laisse le canary à 10 % indéfiniment. C'est pratique pour un test manuel, catastrophique si tu oublies de le retirer.

Ces erreurs ne viennent pas des outils. Elles viennent du fait qu'on branche le routage avant d'avoir défini ce qu'est un canary réussi. Le même travers guette quand on veut maintenir des déploiements automatisés sur le long terme : la mécanique tient, la définition du succès manque.

Mon ordre de mise en place

  1. Exposer un label canary et un label service sur toutes les métriques HTTP. Sans ça, aucun gate n'est possible.
  2. Écrire trois requêtes PromQL : taux de 5xx, p95, redémarrages. Les tester à la main avec curl avant de les mettre dans un CRD.
  3. Choisir un seul service à faible risque pour le premier canary. Pas la facturation.
  4. Brancher les paliers 10 / 30 / 60 % avec des pauses de 5 à 10 minutes.
  5. Ajouter l'annulation automatique sur absence de données, et la tester en coupant volontairement le scrape.
  6. Documenter les seuils dans le repo, à côté du YAML. Un gate non documenté est un gate que personne n'ose modifier.

Compte deux jours pour les étapes 1 à 3, une demi-journée pour le reste. C'est peu au regard du temps passé à regarder Grafana à 2 h du matin en se demandant s'il faut annuler. Cette partie-là, aucun outil ne la règle à ta place, et c'est aussi ce que rappelle l'idée que déployer souvent ne veut pas dire déployer à l'aveugle.

FAQ

Canary ou blue/green ?

Blue/green bascule 100 % du trafic d'un coup, donc le rollback est instantané mais l'exposition est totale. Le canary expose progressivement et détecte les régressions partielles. Si ton service a des effets de bord non réversibles (migrations, files d'attente), le canary avec migration expand/contract est plus sûr.

Combien de temps doit durer un canary ?

Assez pour couvrir un cycle de cache et un pic de trafic : 20 à 30 minutes au total, avec un palier final d'au moins 10 minutes. En dessous de 10 minutes, tu testes le démarrage, pas le comportement.

Faut-il un service mesh ?

Non. La Gateway API et Traefik font du routage pondéré sans sidecar. Le mesh ajoute le routage par en-tête et par utilisateur, utile pour un canary ciblé sur des comptes internes, mais ce n'est pas un prérequis.

Et sans métriques exploitables ?

Commence par les logs structurés et un compteur d'erreurs applicatif exposé en Prometheus. Un canary piloté uniquement par le taux de 5xx reste utile : il attrape les crash loops et les dépendances cassées, soit la moitié des incidents.

Argo Rollouts ou Flagger, en une phrase ?

Argo Rollouts si tu veux écrire tes paliers et tes métriques à la main, Flagger si tu veux un canary qui monte seul avec des tests de charge intégrés.