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.
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
| Couche | Rôle | API typique | Où ça casse |
|---|---|---|---|
| Orchestration | Lancer une seconde version à côté de la première | Kubernetes API, CRD Rollout, Docker API | Deux Deployments qui se battent sur le même label selector |
| Trafic | Router x % vers le candidat | Gateway API HTTPRoute, Istio VirtualService, Traefik, annotations NGINX | Poids appliqué côté client DNS, jamais côté proxy |
| Mesure | Lire les signaux du candidat et du stable | Prometheus /api/v1/query, OTLP, Datadog | Labels absents : impossible de séparer canary et stable |
| Décision | Promouvoir, prolonger ou annuler | AnalysisRun, webhooks Flagger, CI/CD | Gate 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: 60sthreshold: 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ère | Argo Rollouts | Flagger |
|---|---|---|
| Modèle | Étapes déclaratives + AnalysisRun | Montée automatique par paliers |
| Trafic | Traefik, NGINX, Istio, Gateway API, ALB | Istio, Linkerd, App Mesh, Gateway API, NGINX |
| Décision externe | Webhooks pre/post sur le Rollout | Webhooks natifs à 5 points du cycle |
| Test de charge intégré | Non | Oui, via loadtester |
| Courbe d'apprentissage | Moyenne, le YAML est verbeux | Plus 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: 10Basculer 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 :
| Signal | Seuil d'annulation | Fenêtre |
|---|---|---|
| Taux de 5xx | > 1,5× le stable, plancher 0,5 % | 3 min |
| Latence p95 | > 300 ms ou > 1,3× le stable | 5 min |
| Redémarrages de pods | ≥ 1 sur le ReplicaSet canary | durée du rollout |
| Saturation CPU | > 85 % pendant 3 relevés | 3 min |
| Erreur métier | conversion 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
canarysur 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 : garderservice,code,canaryet 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
- Exposer un label
canaryet un labelservicesur toutes les métriques HTTP. Sans ça, aucun gate n'est possible. - Écrire trois requêtes PromQL : taux de 5xx, p95, redémarrages. Les tester à la main avec
curlavant de les mettre dans un CRD. - Choisir un seul service à faible risque pour le premier canary. Pas la facturation.
- Brancher les paliers 10 / 30 / 60 % avec des pauses de 5 à 10 minutes.
- Ajouter l'annulation automatique sur absence de données, et la tester en coupant volontairement le scrape.
- 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.