Skip to content

Runbook: SmokeTestFailing

Alerte : SmokeTestFailing (CI, severity critical)

Symptôme :

Le job Playwright @smoke en CI échoue — un endpoint critique public (docs, MCP health, cockpit root) ne répond plus 200.

Severity : 🔴 critical — c'est la dernière ligne de défense avant prod qui casse.

Diagnostic

1. Identifier le test qui a échoué

# Ouvre les logs GitHub Actions
gh run list --workflow=playwright.yml --limit 1 --json databaseId --jq '.[0].databaseId' | \
  xargs -I {} gh run view {} --log-failed | tail -60

Ou localement :

cd /Users/ab2dridi/newera/akko
export AKKO_DOMAIN=159.195.77.208.nip.io
npx playwright test -g "@smoke" --reporter=list

2. Reproduire l'échec hors CI

# Chaque test @smoke est un simple HTTP GET. Ex:
curl -k https://docs.$AKKO_DOMAIN/ | head -5
curl -k https://mcp-trino.$AKKO_DOMAIN/
curl -k https://mcp-openmetadata.$AKKO_DOMAIN/
curl -k -I https://$AKKO_DOMAIN/      # 302 attendu

3. Déterminer si c'est un faux positif ou un vrai problème

  • Faux positif (réseau CI instable) : re-run ne fail plus
  • Vrai problème (régression) : persiste sur 2+ runs

Causes fréquentes + fix

Cause Symptôme curl Fix
Ingress down connection refused Vérifier kubectl get ingress -n akko + Traefik logs
Certif TLS expiré SSL: CERTIFICATE_VERIFY_FAILED Runbook tls-cert-expires.md
Pod target en CrashLoop 502 ou 503 Runbook pod-crashloop.md
Chemin ingress cassé 404 sur path attendu Vérifier middleware Traefik replacePathRegex
cockpit OAuth2 broken 5xx sur root Runbook keycloak-sso-broken.md
Changement dans un endpoint Test assertion fail Soit rollback soit update du test
Réseau CI instable Intermittent failures Re-run ; si persistant GHA-runner issue

Fix d'urgence (< 10 min)

Cas 1 : régression récente → rollback

# Identifier le commit problématique
git log --oneline -5

# Rollback GitHub (nouveau commit, pas force-push)
git revert <sha>
git push origin main

# Côté k8s : helm rollback
helm history akko -n akko
helm rollback akko <revision> -n akko

Cas 2 : régression intentionnelle → mettre à jour le test

Si un endpoint a changé volontairement (ex: MCP Trino migre de / vers /health), mettre à jour le test :

// tests/playwright/tests/smoke-fix-validation.spec.ts
test('MCP Trino health', async () => {
    const resp = await ctx.get(`https://mcp-trino.${DOMAIN}/health`);  // was `/`
    expect(resp.status()).toBe(200);
});

Commit + push. Tests doivent tourner verts sur le PR.

Fix pérenne (R02)

Ne jamais skip un test qui fail

  • Jamais test.skip() ou test.fixme() en main — c'est de la dette qui se transforme en incident prod.
  • Si un endpoint n'est plus pertinent, supprimer le test (avec explication en commit).

Probe HTTP externe

Ajouter une probe Blackbox externe (check depuis l'extérieur du cluster) : - https://uptimerobot.com (gratuit jusqu'à 50 endpoints) - OR self-hosted blackbox-exporter avec un pod hors-cluster

Runbook par endpoint

Chaque route @smoke doit avoir son propre runbook : - docs.$DOMAIN → MkDocs image akko-docs - mcp-trino.$DOMAIN → runbook dédié - cockpit root → OAuth2 proxy + Keycloak

Prévention

  • Smoke tests à chaque push sur main (déjà en place via playwright.yml)
  • Monitoring externe avec alerting direct vers Slack
  • Synthetic monitoring longue durée : 
    - alert: SmokeEndpointDown
  expr: probe_success{instance=~"docs|mcp-trino|cockpit"} == 0
  for: 3m
  severity: critical
  • Test runbook : vérifier que les runbooks eux-mêmes ne pointent pas vers des dead-links (script tests/check-runbook-links.sh)

Lessons learned

  • L09 — Un test qui fail en CI ≠ un endpoint "cassé". Toujours reproduire localement avant de rollback aveuglément.

Liens utiles