Cache VCL Fastly : tutoriel de mise en cache sécurisé pour la production

Publié le

14 juil. 2026

Mis à jour le

15 juil. 2026

Temps de lecture

23 min de lecture

Fastly peut rendre une réponse publique rapide et peu coûteuse à servir, mais une clé de cache ou un TTL incorrect peut exposer la représentation d'un utilisateur à un autre ou conserver du contenu obsolète plus longtemps que le produit ne l'autorise. Ce tutoriel propose un déploiement restreint et observable pour les ingénieurs DevOps et web qui exploitent un service Fastly VCL. Cette discipline compte encore plus lorsque la route se trouve derrière un edge managé et multi-fournisseurs : une couche d'orchestration qui ajoute le cache VCL Fastly à une pile qu'elle observe et sécurise par ailleurs a besoin que la clé de cache, le TTL et les décisions de pass de chaque route soient démontrables à la demande, pas seulement corrects le jour de leur mise en production.

Prérequis

Avant de modifier le trafic de production, disposez de tous les éléments suivants :

• Un accès permettant de créer et d'activer une nouvelle version du bon service Fastly. Confirmez son ID de service, ses domaines et l'équipe propriétaire de l'origine.
• Une version active connue comme fiable et une personne nommément autorisée à la réactiver. Les configurations de service Fastly sont versionnées ; l'activation est une action opérationnelle distincte de la modification.
• Une URL de test d'origine ou un objet public à faible risque dont la réponse est stable, non personnalisée et sûre à mettre en cache.
• Un moyen de comparer la charge d'origine, le taux d'erreur, l'état du cache et un parcours utilisateur représentatif avant et après le changement.
• Un contrat d'origine pour la route : méthodes autorisées, comportement d'authentification, cookies, paramètres de requête, variantes de contenu, responsable de l'invalidation et obsolescence maximale acceptable.

Ne commencez pas par la connexion, le paiement, le compte, les résultats de recherche, les API dépendantes de l'autorisation, ni toute réponse qui définit ou reflète un état utilisateur. Une amélioration de cache qui modifie la justesse n'est pas une amélioration.

Scénario Acme Shop

Acme Shop diffuse les images publiques de son catalogue à l'adresse https://shop.example.test/assets/products/red-mug.webp. L'origine renvoie une image stable, et c'est l'équipe produit qui possède l'invalidation. Ses routes /account et /checkout utilisent des sessions et ne doivent jamais utiliser le cache partagé. Commencez par cette unique route d'image, pas par tout le catalogue.

Le principe de décision reste simple : seule une requête anonyme pour l'espace de noms d'images publiques atteint la recherche en cache. Une requête porteuse d'une identité ou d'un cookie passe directement à l'origine via PASS. Parmi les requêtes anonymes éligibles, une recherche en cache produit soit un HIT, soit une récupération marquée MISS. Seule une réponse sûre pour un stockage partagé reçoit le TTL explicite défini plus loin dans ce guide.

1. Cartographier le service et le chemin d'activation du backend

Dans Fastly, un service contient la configuration de diffusion. Un backend décrit l'emplacement depuis lequel Fastly récupère la réponse lorsqu'il doit joindre l'origine. Rendez cette relation explicite avant d'écrire du VCL :

1. Identifiez la version de service qui sert actuellement le nom d'hôte et conservez son numéro de version comme cible de restauration immédiate.
2. Confirmez quel backend sert la route de test, y compris son adresse, les attentes concernant l'en-tête Host, le comportement de santé, les paramètres TLS, les délais d'attente et toute configuration de shielding existante.
3. Clonez ou créez autrement une version de service modifiable conformément aux recommandations de Fastly sur le versionnement des services. Ne modifiez pas une configuration de production sans connaître la version que vous activerez et celle que vous rétablirez.
4. Ajoutez la modification de backend ou de VCL uniquement à la nouvelle version, examinez le diff généré avec le propriétaire de l'origine, puis activez cette version dans un créneau planifié. Le guide des backends de Fastly présente les concepts et le comportement de configuration des backends.

L'activation modifie le trafic réel ; la création d'une version de brouillon ne le fait pas. Conservez un court enregistrement du changement contenant l'ID de service, les anciennes versions et candidates, les routes concernées, l'état de cache attendu, la requête de validation et la version de restauration.

2. Définir d'abord le contrat de cache effectif

Écrivez la politique visée en langage clair avant de la traduire en en-têtes ou en VCL. Par exemple : « GET /assets/* est public, varie uniquement selon le chemin normalisé, reste frais chez Fastly pendant une heure, peut rester obsolète pendant cinq minutes pendant la revalidation et doit pouvoir être purgé lors d'une livraison. »

Fastly détermine la fraîcheur à partir des en-têtes de réponse d'origine dans l'ordre de priorité documenté : Surrogate-Control, puis Cache-Control: s-maxage, puis Cache-Control: max-age, puis Expires. Surrogate-Control est utile lorsque les navigateurs nécessitent une politique plus courte que Fastly. Pour l'ordre de priorité exact et les divergences documentées avec RFC 9111, consultez À propos des en-têtes de contrôle du cache et Fraîcheur du cache.

VCL peut remplacer la durée de vie en périphérie. Dans vcl_fetch, beresp.ttl contrôle le TTL de l'objet mis en cache par Fastly ; réécrire beresp.http.Cache-Control à cet endroit ne modifie pas rétroactivement le TTL déjà calculé par Fastly. Inversement, modifier uniquement beresp.ttl ne définit pas le comportement du navigateur. Séparez intentionnellement les politiques de périphérie et de navigateur.

Ne comptez pas sur le comportement de repli de Fastly comme politique. Fastly documente un TTL par défaut de 3600 secondes (une heure) pour une réponse par ailleurs cacheable qui ne porte aucun des en-têtes Surrogate-Control, Cache-Control ou Expires ; un service en VCL personnalisé qui atteint vcl_fetch sans aucun en-tête de fraîcheur présent peut au contraire voir beresp.ttl se fixer sur un repli plus court avant même que votre propre logique ne s'exécute. Dans les deux cas, une réponse qui « se trouve » cacheable pour une durée implicite n'est pas un contrat que quiconque a examiné. Écrivez l'en-tête explicite, ou le set beresp.ttl explicite, et traitez un objet qui ne survit que grâce à un repli par défaut comme un bug à corriger, pas comme un comportement dont on peut dépendre.

Ce cycle de vie complet, délibérément restreint, correspond à la route d'assets publics d'Acme Shop. Ajoutez-le à une configuration VCL personnalisée revue, au bon emplacement pour le service ; ne remplacez pas aveuglément la logique générée par Fastly.

sub vcl_recv {
  if (req.method != "GET" && req.method != "HEAD") {
    return (pass);
  }

  # Le premier déploiement n'admet que l'espace de noms d'images publiques connu et versionné.
  if (req.url !~ "^/assets/products/") {
    return (pass);
  }

  # Toute présence d'identité ou de cookie rend la requête inéligible au cache partagé.
  if (req.http.Authorization || req.http.Cookie) {
    return (pass);
  }

  return (lookup);
}

sub vcl_fetch {
  if (bereq.url !~ "^/assets/products/") {
    return (pass);
  }

  # Fastly n'utilise pas ces directives lorsqu'il calcule beresp.ttl par défaut.
  # Évaluez-les, ainsi que Set-Cookie, avant de définir un TTL de périphérie explicite.
  if (beresp.http.Set-Cookie ||
      beresp.http.Cache-Control ~ "(?i)(private|no-store)" ||
      beresp.http.Surrogate-Control ~ "(?i)(private|no-store)") {
    return (pass);
  }

  set beresp.ttl = 1h;
  set beresp.stale_while_revalidate = 5m;
  return (deliver);
}

Cet exemple est un modèle de départ, pas une politique à copier-coller. Les vérifications de réponse doivent précéder beresp.ttl : l'analyse du TTL par défaut de Fastly ne respecte pas d'elle-même private ou no-store, et une réponse portant Set-Cookie ne doit jamais entrer dans un objet partagé. Ne définissez un comportement obsolète que lorsque le propriétaire du contenu accepte de servir une représentation plus ancienne. Conservez ou définissez délibérément les en-têtes destinés au navigateur séparément, et testez la réponse produite par votre véritable origine.

3. Choisir ensemble la clé de cache et le TTL VCL

La clé de cache par défaut de Fastly est construite dans vcl_hash à partir de req.url et de req.http.host ; chaque service intègre aussi req.vcl.generation, afin qu'un purge-all à l'échelle du service continue d'invalider correctement les objets. Bien choisir la clé de cache et TTL VCL ensemble compte parce que les deux se compensent : une clé large avec un TTL long fragmente le cache en de nombreux objets rarement réutilisés, tandis qu'une clé étroite avec un TTL long est exactement la manière dont la réponse d'un utilisateur finit par être servie à un autre. Ne modifiez la clé par défaut que lorsque le contrat applicatif l'exige, et revérifiez la décision de TTL chaque fois que la clé change.

Pour chaque route candidate, documentez les questions suivantes :

• Quelle normalisation de chemin est sûre ? Ne fusionnez pas les chemins si l'origine les distingue.
• Quels paramètres de requête modifient la représentation ? Ne supprimez les paramètres de suivi connus qu'après avoir prouvé qu'ils n'affectent pas la réponse.
• La langue, le format de l'appareil, l'affectation d'expérience ou un en-tête de requête modifie-t-il la réponse ? Préférez une politique Vary contrôlée lorsqu'elle est appropriée plutôt qu'une clé personnalisée non examinée.
• Des cookies, Authorization, un en-tête de session ou un identifiant de compte peuvent-ils influencer le corps ? Si oui, ne placez pas cette réponse dans un cache public partagé sans clé délibérément isolée et revue de sécurité.

Évitez d'utiliser une valeur brute de cookie ou d'autorisation dans une clé partagée. Cela fragmente le cache, risque d'exposer des données sensibles dans les surfaces opérationnelles et peut encore être incorrect si d'autres entrées d'identité sont omises. Les bonnes pratiques de mise en cache de Fastly abordent le comportement de clé par défaut et le compromis entre fragmentation et fusion dangereuse.

Lorsqu'un véritable changement de clé est justifié, faites-le explicitement dans vcl_hash plutôt que de vous tourner d'abord vers une politique Vary plus large. Pour Acme Shop, supposons qu'un second format d'image ait besoin de son propre objet parce que l'origine ne peut pas varier de façon fiable sur Accept :

sub vcl_hash {
  set req.hash += req.url;
  set req.hash += req.http.host;

  # Étendez la clé par défaut uniquement pour l'en-tête dont cette route a besoin.
  if (req.url ~ "^/assets/products/" && req.http.Accept-Format) {
    set req.hash += req.http.Accept-Format;
  }

  # Nécessaire pour qu'un purge-all invalide encore chaque génération de cette clé.
  set req.hash += req.vcl.generation;
  return (hash);
}

Deux conséquences découlent directement des indications de Fastly sur la manipulation de la clé de cache et de la référence req.hash : d'abord, chaque valeur ajoutée multiplie le nombre d'objets distincts que Fastly doit remplir et purger, si bien qu'une purge par clé de substitution (surrogate key) ou par URL doit désormais tenir compte de chaque dimension ajoutée ; ensuite, omettre req.vcl.generation d'un vcl_hash personnalisé casse silencieusement le purge-all pour cette route, car le marqueur de génération est ce qui relie une opération de purge-all à chaque objet haché. Testez un changement de clé personnalisé avec une purge explicite, pas seulement avec une vérification de cache-hit.

4. Comprendre le comportement pass Fastly avant de s'y appuyer

return(pass) est un contrôle de justesse pour les requêtes ou réponses qui ne doivent pas être servies par le chemin normal du cache, et le comportement pass Fastly diffère sensiblement selon l'endroit où il se produit. Un pass de requête dans vcl_recv ignore purement et simplement la recherche et le regroupement des requêtes. Un pass de réponse dans vcl_fetch intervient après une recherche et une récupération d'origine ; Fastly documente qu'une réponse cacheable atteinte de cette manière crée un objet hit-for-pass plutôt que de simplement ne rien mettre en cache.

sub vcl_recv {
  if (req.method != "GET" && req.method != "HEAD") {
    return (pass);
  }

  if (req.http.Authorization || req.http.Cookie) {
    return (pass);
  }
}

Les noms de route et de cookie ci-dessus sont des exemples. N'ajoutez pas de pass large sur les cookies sans mesurer la perte de possibilité de mise en cache, et ne les supprimez pas tant que le contrat de réponse ne prouve pas que l'objet est public.

L'objet hit-for-pass compte sur le plan opérationnel, pas seulement sémantique. La documentation de Fastly sur le regroupement des requêtes explique que, tant qu'un objet hit-for-pass existe, chaque requête pour cette clé est envoyée directement à l'origine comme si elle avait fait un pass dans vcl_recv, désactivant délibérément le regroupement des requêtes pour cette clé. Son TTL est d'environ deux minutes par défaut, et reste sinon borné par la valeur de beresp.ttl que vous définissez avant de retourner un pass depuis vcl_fetch ; une fois qu'il expire, la requête suivante est un miss normal et le regroupement reprend. Une route qui passe de façon intermittente à cause d'un en-tête d'origine incohérent peut donc voir la charge d'origine grimper juste après l'expiration de chaque objet hit-for-pass, ce qui ressemble à une régression de cache mais est en réalité une incohérence du contrat de réponse.

Si vous devez forcer une récupération unique tout en conservant le comportement de cache normal, Fastly documente que req.hash_always_miss diffère de return(pass). Utilisez-le uniquement dans un test temporaire à périmètre étroit et supprimez-le après validation.

5. Gérer les pannes d'origine sans casser le cache VCL Fastly

Une clé de cache et un TTL corrects ne suffisent pas si l'origine devient lente ou instable : les mêmes décisions de cache VCL Fastly qui gardent les images produit d'Acme Shop rapides en fonctionnement normal doivent aussi décider de ce qui se passe lorsque l'origine ne peut plus répondre du tout. Fastly distingue deux comportements liés mais différents, et les confondre est une source fréquente de surprise :

• stale-while-revalidate sert immédiatement un objet récemment expiré pendant que Fastly le revalide en arrière-plan, ce qui borne la latence perçue sans jamais exposer le client à une panne d'origine.
• stale-if-error (et l'équivalent beresp.grace) garde un objet obsolète éligible à être servi spécifiquement lorsque l'origine renvoie une erreur ou est inaccessible, ce qui est un contrôle de résilience plutôt qu'un contrôle de latence.

sub vcl_fetch {
  if (bereq.url !~ "^/assets/products/") {
    return (pass);
  }

  if (beresp.http.Set-Cookie ||
      beresp.http.Cache-Control ~ "(?i)(private|no-store)" ||
      beresp.http.Surrogate-Control ~ "(?i)(private|no-store)") {
    return (pass);
  }

  set beresp.ttl = 1h;
  set beresp.stale_while_revalidate = 5m;
  set beresp.stale_if_error = 1d;

  # Une origine défaillante ne doit pas transformer une image produit mise en cache en 5xx.
  if (beresp.status >= 500 && beresp.status < 600 && stale.exists) {
    return (deliver_stale);
  }

  return (deliver);
}

Si le VCL définit beresp.grace, Fastly documente qu'il l'emporte sur toute valeur stale-if-error provenant des propres en-têtes Cache-Control ou Surrogate-Control de l'origine ; choisissez donc une seule source de vérité pour cette durée, sans vous attendre à ce que les deux s'additionnent. Décidez délibérément de la durée de stale_if_error : pour les images produit d'Acme Shop, servir une image vieille d'un jour pendant une panne d'origine est un compromis acceptable que l'équipe catalogue peut assumer ; pour une réponse de prix ou de stock, le même réglage pourrait servir un chiffre incorrect et exige une fenêtre bien plus courte, voire aucune. Consultez le guide Fastly sur servir du contenu obsolète pour le contrat complet de deliver_stale dans vcl_fetch et vcl_error.

6. Ajouter le shielding seulement après avoir validé le chemin de base

Le shielding envoie les misses de périphérie vers un POP de shielding Fastly choisi avant l'origine. Il peut protéger l'origine et améliorer la réutilisation entre les POP de périphérie, mais il modifie le chemin de requête et peut faire exécuter le VCL plus d'une fois. Ajoutez-le après avoir compris le comportement de cache sans shielding, et non dans le même premier changement.

Lors de l'évaluation du shielding :

• Choisissez et testez un emplacement de shielding adapté à l'origine et à son chemin réseau.
• Vérifiez que les contrôles d'accès à l'origine autorisent le chemin de requête shielded et que les journaux d'origine conservent un ID de corrélation de requête exploitable.
• Rendez les mutations d'en-têtes de réponse sûres en cas de double exécution. Fastly recommande de distinguer le POP connecté au client lors de l'application de changements de réponse destinés au client.
• Interprétez les diagnostics de cache dans le contexte du shielding : un miss de périphérie suivi d'un hit de shield évite une requête à l'origine, tandis que les calculs globaux de cache-hit peuvent inclure les deux événements.

Lisez Shielding avant de l'activer. Cette documentation couvre la double exécution, l'interprétation de l'état du cache et le risque que les changements de réponse effectués au mauvais endroit soient mis en cache en aval.

7. Tester, activer et valider par étapes

Utilisez d'abord une route à faible risque et une version de service candidate. N'apportez pas un changement large de clé de cache et un changement large de TTL dans la même livraison.

1. Capturez une réponse de référence de l'URL de test, y compris l'état, le hash du corps, Cache-Control, Age, X-Cache, X-Cache-Hits, X-Served-By et le nombre de requêtes d'origine.
2. Exercez les variantes attendues : une requête anonyme simple, chaque langue ou représentation prévue, une requête avec paramètre de suivi et une requête authentifiée ou porteuse de cookie qui doit passer.
3. Activez la version candidate seulement après avoir consigné les résultats attendus. Envoyez un petit nombre de requêtes contrôlées, puis comparez les hashes de corps et les en-têtes avec la référence.
4. Confirmez la séquence attendue : un objet froid peut être un miss, une requête équivalente répétée devrait devenir un hit dans son TTL, et une requête qui doit passer ne devrait pas réutiliser l'objet public. Vérifiez le parcours applicatif ainsi que les en-têtes.
5. Si le shielding est activé, validez les diagnostics de périphérie et de shield, et confirmez que l'origine reçoit moins de requêtes équivalentes plutôt que de simples en-têtes de cache différents.
6. Étendez progressivement le trafic ou les routes, surveillez le taux de cache-hit avec le taux de requêtes d'origine, la latence, les erreurs et les conversions métier, puis documentez le comportement observé.

Le guide Vérifier le cache de Fastly explique les vérifications basées sur curl et les en-têtes de débogage. Considérez Fastly-Debug comme un accès de diagnostic : il peut exposer des informations normalement supprimées des réponses ; utilisez-le donc uniquement depuis des outils autorisés et ne l'exposez pas aux clients.

Pour Acme Shop, n'exécutez ces vérifications que contre l'hôte de préproduction ou un objet de test de production approuvé. Comparez la somme de contrôle du corps autant que les en-têtes :

curl -sS -D - -o /dev/null https://shop.example.test/assets/products/red-mug.webp
curl -sS -D - -o /dev/null https://shop.example.test/assets/products/red-mug.webp
curl -sS -D - -o /dev/null -H 'Cookie: session=demo' https://shop.example.test/account

Une exécution représentative de la deuxième requête renvoie un HTTP/2 200 avec Cache-Control: public, max-age=300, un Age supérieur à zéro et X-Cache: HIT.

• Positif : la requête anonyme répétée sur l'asset renvoie la même somme de contrôle et devient un HIT dans le TTL d'une heure défini en périphérie.
• Négatif : /account avec le cookie de session synthétique ne réutilise pas l'objet de l'asset et suit un comportement PASS.
• Échec : une somme de contrôle modifiée, une réponse de compte portant des en-têtes de cache partagé, des 5xx inattendus, ou une charge d'origine dépassant le seuil d'arrêt signifient qu'il faut arrêter le déploiement et réactiver la version précédente.

Restauration

La restauration doit être plus rapide que le diagnostic en cas de fuite de cache suspectée, de contenu critique obsolète ou de régression de l'origine :

1. Arrêtez d'étendre le déploiement et consignez les horodatages, les ID de requête, les motifs d'URL affectés et la version de service candidate.
2. Réactivez la version de service connue comme fiable. Vérifiez la version active, puis relancez les mêmes requêtes contrôlées.
3. Si des objets incorrects peuvent rester en cache, effectuez une purge ciblée seulement après avoir confirmé son périmètre et son propriétaire. Une purge ne corrige pas à elle seule une clé non sûre ; rétablissez d'abord un comportement sûr.
4. Confirmez que les parcours anonymes et authentifiés, la charge d'origine, le taux d'erreur et les diagnostics de cache sont revenus à l'état attendu.
5. Conservez les éléments de preuve et corrigez la version candidate hors ligne. Ne la réactivez pas sur la seule base d'un unique cache hit ou miss.

Dépannage

Pièges courants

• Supposer que no-cache ou no-store signifie que Fastly ne mettra pas en cache : Fastly documente une sémantique différente. Utilisez ses contrôles documentés et testez le résultat effectif.
• Modifier un en-tête de réponse et supposer que le TTL de périphérie a changé : En VCL, utilisez beresp.ttl pour le TTL Fastly ; les en-têtes de navigateur constituent une politique distincte.
• Mettre en cache une réponse qui varie selon l'identité : Une dimension de clé manquante peut divulguer des données. Passez d'abord ; concevez un contrat de cache sûr ensuite.
• Ajouter chaque paramètre de requête, cookie ou en-tête à la clé : Cela transforme un objet réutilisable en nombreux misses et peut surcharger l'origine.
• Utiliser pass partout pour faire disparaître un symptôme : Cela peut supprimer le regroupement de requêtes et masquer l'erreur sous-jacente du contrat de réponse tout en augmentant le trafic d'origine.
• Activer le shielding avec des mutations de réponse destinées au client : Le service peut s'exécuter deux fois, et une mutation au shield peut être stockée par les POP de périphérie.
• Valider uniquement X-Cache : Un hit ne prouve ni que le corps ni que la variante sont corrects. Comparez le contenu, les en-têtes, le comportement applicatif et la télémétrie d'origine.
• Définir beresp.grace et stale_if_error en s'attendant à ce qu'ils s'additionnent : Fastly documente qu'une instruction VCL grace l'emporte sur stale-if-error provenant des en-têtes de réponse ; choisissez une seule source de vérité.
• Oublier req.vcl.generation après avoir personnalisé vcl_hash : cela casse silencieusement le purge-all pour cette route bien avant que quiconque ne remarque un objet obsolète.

Références Fastly principales

• Travailler avec les versions de service
• Travailler avec les backends
• À propos des en-têtes de contrôle du cache
• Fraîcheur du cache
• Écrire du code VCL
• Bonnes pratiques VCL
• Manipuler la clé de cache
• Servir du contenu obsolète
• Regroupement des requêtes
• Shielding
• Vérifier le cache
• Bonnes pratiques de mise en cache
• À propos de Fastly VCL
• Durée de vie et revalidation