Azure APIM self-hosted gateway : diagnostiquer une désynchronisation avant de rerouter le trafic

Une passerelle self-hosted Azure API Management peut continuer à répondre alors qu’elle n’est plus alignée avec le service APIM qui la pilote. C’est le piège opérationnel : le trafic passe encore, mais une nouvelle policy n’est pas appliquée, une API reste absente, une route renvoie une ancienne réponse, ou un cluster secondaire semble prêt alors qu’il sert une configuration dépassée.

Le cas d’usage est un APIM central dans Azure et des gateways self-hosted déployées sur Kubernetes, proches des backends internes ou hybrides. Une équipe veut rerouter une partie du trafic vers un autre cluster après un incident réseau ou une maintenance. Avant de changer DNS, Front Door, Application Gateway ou un load balancer interne, le runbook doit prouver que la gateway cible est synchronisée, authentifiée, observable et capable de joindre les backends attendus.

Figer le risque avant le basculement

Commencez par écrire ce que le reroutage doit changer. Une bascule de trafic n’est pas une correction neutre si la passerelle cible n’a pas la même configuration que la passerelle active.

change:
apim_service: apim-prod-core
gateway_active: shgw-aks-west
gateway_target: shgw-aks-east
api: payments-api
operation: POST /payments/authorize
traffic_shift: 25_percent_canary
reason: regional maintenance on the active Kubernetes cluster

evidence_required:
- target gateway pods ready
- configuration downloaded after the last APIM policy change
- gateway authentication still valid
- backend route works from the target cluster
- logs or local traces available for the canary
- rollback restores previous traffic path

Cette fiche empêche une décision trop rapide : “le pod est Ready” ne prouve pas que la gateway applique la bonne configuration ni qu’elle peut joindre le backend réel.

Séparer plan de contrôle, runtime et backend

Le diagnostic doit distinguer trois plans. Le plan de contrôle synchronise la configuration depuis Azure API Management. Le runtime reçoit les requêtes et applique les policies. Le plan backend joint les services exposés derrière la gateway.

Plan de controle
La gateway doit s'authentifier aupres d'APIM et telecharger la configuration
Risques: token expire, Workload Identity mal liee, DNS ou sortie 443 bloquee, ancienne configuration en cache

Runtime gateway
Les pods doivent recevoir le trafic, appliquer policies, products, subscriptions et transformations
Risques: version differente, replica non pret, secret absent, config locale incoherente

Plan backend
La gateway doit joindre le backend avec le bon hostname, TLS, route, identite et timeout
Risques: DNS cluster, NetworkPolicy, firewall, certificat backend, UDR, NAT ou allowlist source

Un symptôme applicatif peut venir de n’importe lequel de ces plans. Rerouter le trafic avant de les séparer peut déplacer l’incident au lieu de le résoudre.

Vérifier l’état Kubernetes réel

Le premier contrôle est local au cluster. Il doit confirmer la version déployée, les redémarrages, les secrets montés, les probes et les derniers logs de synchronisation.

NAMESPACE="apim-gateway"
APP_LABEL="app.kubernetes.io/name=azure-api-management-gateway"

kubectl get pods -n "$NAMESPACE" -l "$APP_LABEL" -o wide
kubectl describe deployment -n "$NAMESPACE" -l "$APP_LABEL"
kubectl get events -n "$NAMESPACE" --sort-by=.lastTimestamp | tail -40

kubectl logs -n "$NAMESPACE" -l "$APP_LABEL" --tail=200 | egrep -i "config|sync|token|auth|error|warning|backend|certificate"

Un redémarrage récent peut être normal après une rotation de token ou un upgrade Helm. Il devient suspect si la gateway démarre avec une configuration ancienne, répète des erreurs d’authentification ou ne télécharge plus les mises à jour APIM.

Qualifier l’authentification de la gateway

La gateway self-hosted doit s’authentifier auprès de l’instance APIM associée pour récupérer la configuration. Selon le déploiement, l’équipe peut utiliser un token de gateway, une identité Entra ID ou Workload Identity sur AKS. Le risque n’est pas seulement l’expiration : c’est aussi la rotation non propagée, un secret monté dans un mauvais namespace ou une fédération d’identité qui ne correspond plus au service account.

Controle token ou identite
La methode d'authentification attendue est documentee
Le secret ou service account utilise par les pods est celui de production
La rotation recente a ete appliquee sur tous les replicas
Les logs ne contiennent pas de refus auth ou token expire
Le dernier demarrage est posterieur au changement de secret si une rotation a eu lieu

Suspendre le reroutage quand
Un pod utilise encore l'ancien token
La gateway cible ne telecharge plus la configuration
Les evenements indiquent une erreur de montage secret
La federation d'identite ne matche pas le namespace ou service account

Si l’authentification est douteuse, le rollback n’est pas de changer les routes. Il consiste à remettre la gateway en mode non cible, corriger le secret ou l’identité, puis attendre une synchronisation prouvée.

Prouver la synchronisation de configuration

Le point clé est de relier la configuration servie par la gateway au dernier changement APIM pertinent : policy, API, product, subscription, backend ou certificat. Une gateway peut survivre temporairement à une perte de connectivité Azure grâce à une configuration locale, mais ce comportement ne doit pas être confondu avec une synchronisation saine.

GATEWAY_URL="https://shgw-east.internal.example.com"
API_PATH="/payments/authorize"
CORRELATION_ID="diag-$(date +%Y%m%d%H%M%S)"

curl -sk -D - -H "x-correlation-id: $CORRELATION_ID" -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" "$GATEWAY_URL$API_PATH?diagnostic=true"

echo "Correlation: $CORRELATION_ID"

La requête de preuve doit traverser la même API, la même policy et le même backend que le trafic à basculer. Un endpoint de santé générique prouve seulement que le conteneur répond.

Contrôler le chemin backend depuis la gateway cible

Une gateway synchronisée peut encore échouer si le cluster cible ne résout pas le backend, sort par une IP non autorisée ou utilise un certificat racine différent. Avant de rerouter, exécutez les contrôles depuis le même namespace et, si possible, avec une image de diagnostic soumise aux mêmes NetworkPolicies.

NAMESPACE="apim-gateway"
BACKEND_HOST="payments.internal.example.com"
BACKEND_URL="https://payments.internal.example.com/health"

kubectl run apim-path-check -n "$NAMESPACE" --rm -i --restart=Never --image=curlimages/curl:latest -- sh -c "nslookup $BACKEND_HOST && curl -sk -w '
http_code=%{http_code}
remote_ip=%{remote_ip}
' $BACKEND_URL"

Si ce test échoue, évitez de modifier les policies APIM. Le problème est probablement dans DNS, routage, firewall, TLS backend, NetworkPolicy ou allowlist source.

Lire les traces disponibles

La gateway self-hosted ne se diagnostique pas exactement comme la gateway managée APIM. Selon la configuration, les resource logs Azure Monitor ne couvrent pas tout le runtime self-hosted. Il faut donc prévoir des logs locaux, une collecte Kubernetes, des métriques cloud si elles sont activées, et des identifiants de corrélation propagés au backend.

let CorrelationId = "diag-20260726143000";
AppRequests
| where TimeGenerated > ago(30m)
| where tostring(CustomDimensions["x-correlation-id"]) == CorrelationId
| project TimeGenerated, AppRoleName, Name, ResultCode, DurationMs, OperationId, CloudRoleInstance
| order by TimeGenerated asc

L’absence de log backend pour la corrélation indique que la requête n’a probablement pas atteint le service. Un 401, 403, 502 ou 504 avec corrélation donne au contraire une couche de correction plus précise.

Décider reroutage, correction ou rollback

La décision doit rester bornée. Une gateway cible non synchronisée ne devient pas sûre parce que le cluster est disponible.

Autoriser le canary
Pods stables et version attendue
Authentification gateway valide
Configuration synchronisee apres le dernier changement APIM
Requete de preuve sur la vraie API reussie
Backend joignable depuis le cluster cible
Logs locaux ou correlation backend exploitables
Rollback de routage teste

Corriger avant reroutage
Token expire ou secret non propage
Workload Identity non associee au bon service account
DNS ou sortie 443 vers APIM bloquee
Backend resolu differemment depuis le cluster cible
Logs insuffisants pour qualifier le canary

Rollback
Le canary sert une ancienne policy
Les erreurs augmentent sans trace exploitable
La gateway cible perd la synchronisation pendant la fenetre
Le backend refuse la nouvelle source reseau
Le retour au chemin precedent restaure la reponse attendue

Le rollback le plus propre consiste à remettre le poids de trafic précédent, conserver les corrélations du canary, puis corriger la gateway hors flux utilisateur. Ne régénérez pas aveuglément tous les tokens si un seul cluster est en dérive.

Valider après retour au calme

Après correction ou rollback, rejouez la même requête de preuve, vérifiez la synchronisation après un changement APIM contrôlé et documentez le temps nécessaire à la propagation. Cette mesure devient une donnée de runbook pour les prochaines bascules.

A conserver
Dernier changement APIM avant incident
Heure de detection de la desynchronisation
Methode auth utilisee par la gateway
Cause exacte: token, identite, sortie 443, DNS, backend ou logs
Duree de propagation observee apres correction
Commande ou procedure de rollback validee
Signal a ajouter a la supervision

Conclusion

Une gateway APIM self-hosted est une frontière d’exécution distribuée. Elle peut être saine côté Kubernetes et pourtant dangereuse à exposer si sa configuration, son authentification ou son chemin backend ne sont pas prouvés.

Le bon réflexe avant un reroutage est simple : vérifier le pod, prouver l’authentification, relier la configuration au dernier changement APIM, tester le vrai backend depuis le cluster cible, garder une corrélation lisible et préparer le rollback de trafic. La bascule devient alors une décision de production, pas un pari sur un endpoint qui répond.