Déploiement Cloudflare Workers en toute sécurité

Publié le

14 juil. 2026

Mis à jour le

15 juil. 2026

Temps de lecture

29 min de lecture

Un déploiement Cloudflare Workers qui n'a besoin de fonctionner qu'une seule fois est facile ; un déploiement qui doit fonctionner de la même manière chaque semaine, pour chaque handler edge dont dépend une activité, est une discipline opérationnelle. C'est exactement l'exigence à laquelle une couche d'orchestration edge managée se tient elle-même : rollout progressif, canari mesurable et chemin de retour testé, appliqués de façon cohérente que le runtime derrière une route donnée soit celui de Cloudflare ou d'un autre partenaire.

Cloudflare Workers convient particulièrement au façonnage des requêtes à proximité des utilisateurs : contrôles d'authentification, redirections, politique de cache, normalisation des en-têtes, composition d'API légère et routage entre services. Ce n'est pas un remplacement par défaut de tous les backends. Commencez par déterminer si la charge de travail est suffisamment sans état et bornée pour un runtime edge, puis déployez-la dans des environnements explicites avec un chemin de retour testé.

Ce guide s'adresse aux ingénieurs DevOps et plateforme qui exploitent Workers comme infrastructure de production. Il suppose que l'équipe applicative possède la logique du handler tandis que l'équipe plateforme possède les contrôles de déploiement, les secrets, l'exposition au trafic et la visibilité opérationnelle.

Résultat visé et scénario Acme Shop. Acme Shop déploie un Worker de catalogue public typé : d'abord en staging, puis un candidat de production chargé sans trafic, puis un petit split de version. La fiche de release consigne la version stable, le candidat, les conditions d'arrêt et la commande wrangler rollback à utiliser. Le Worker sert GET /edge/catalog en interrogeant l'API de catalogue public d'Acme Shop ; il ne gère ni paiement, ni compte, ni écriture d'inventaire, ni identifiant. L'URL amont est une configuration non secrète, tout identifiant amont restant un Worker secret géré à part. Pendant un déploiement progressif, l'ancienne et la nouvelle version servent des requêtes en même temps, donc leurs contrats doivent rester compatibles entre eux.

Prérequis pour un déploiement Cloudflare Workers

Avant de modifier le trafic, mettez en place les éléments suivants pour ce déploiement Cloudflare Workers :

• Un compte Cloudflare autorisé à créer et déployer des Workers, gérer la route cible ou le custom domain et lire les analytics Worker.
• Une installation locale de Wrangler authentifiée auprès du compte visé. Cloudflare documente les méthodes d'installation et de connexion prises en charge dans Get started with Wrangler.
• Un projet Worker adossé à Git avec une configuration wrangler.jsonc, wrangler.json ou wrangler.toml revue.
• Des environnements de déploiement hors production et de production séparés, avec des secrets et bindings distincts lorsque nécessaire.
• Un responsable de rollback, une destination d'alerte et une version connue comme bonne déjà déployée avant d'activer une nouvelle route ou version.
• Une décision sur les réglages d'observabilité Workers par défaut pour chaque environnement : si les Logs sont activés, et à quel taux d'échantillonnage, avant que le premier candidat ne parte en production plutôt qu'après un incident.

Étape 1 : confirmer que la charge de travail convient à l'edge

Définissez le contrat du Worker avant de choisir des bindings ou d'écrire une route. Un bon contrat edge possède un chemin de requête petit et déterministe et délègue les transactions durables, les travaux de longue durée ou le traitement de grands volumes de données aux services backend appropriés.

Vérifiez les contraintes de plateforme actuelles par rapport au comportement proposé :

• Consultez les Workers limits pour les limites de temps CPU, mémoire, requête, sous-requête et taille de script. Les limites varient selon le plan et peuvent évoluer ; traitez donc la documentation comme la source de vérité pour le compte sur lequel vous déploierez.
• Consultez les runtime APIs pour la compatibilité au lieu de supposer que les API serveur Node.js sont disponibles.
• Assurez-vous que toute dépendance sortante est joignable depuis le Worker et possède des timeouts explicites et une gestion des erreurs dans le code applicatif.
• Gardez les données personnelles, identifiants et configurations spécifiques au tenant hors du code source et des vars en texte clair lorsqu'il s'agit de secrets.

Le temps CPU et le temps d'horloge murale ne sont pas le même budget, et les confondre est une erreur fréquente d'évaluation de l'adéquation edge. Le plan gratuit documenté par Cloudflare limite le temps CPU à 10 ms par requête HTTP, plafond non ajustable ; le plan payant part à 30 secondes par défaut, configurable jusqu'à 5 minutes. Attendre un fetch(), une lecture KV ou une requête D1 ne compte pas dans ce budget — seul le temps que le CPU passe à exécuter votre code compte. Le AbortSignal.timeout(1_500) du handler Acme Shop plus bas borne l'attente de l'API de catalogue amont ; c'est un contrôle de temps d'horloge, pas de temps CPU. Un Worker qui fait de la transformation JSON, du templating ou de la cryptographie lourde à chaque réponse peut épuiser son budget CPU avant même qu'un timeout réseau ne se déclenche : révisez donc le temps CPU dès que le handler traite le corps de la requête ou de la réponse de façon non triviale, pas seulement lorsqu'il appelle un amont lent.

Réserve sur la logique métier à état

Workers peut coordonner l'état via des produits tels que Durable Objects, KV, D1, R2, Queues et des services externes, mais une invocation Worker individuelle n'est pas un serveur applicatif transactionnel durable. Ne placez pas la réservation d'inventaire, le règlement de paiement, la mutation de compte ou d'autres workflows métier exactly-once uniquement dans du code Worker local à la requête. Concevez un backend faisant autorité, des clés d'idempotence, un comportement de retry et une piste d'audit durable. Si vous utilisez Durable Objects, comprenez leur modèle de localisation et de concurrence via Durable Objects.

Étape 2 : définir la configuration, les secrets et les bindings

Conservez la configuration de déploiement non secrète dans le fichier Wrangler et provisionnez les secrets via Wrangler ou le dashboard Cloudflare. Cloudflare précise explicitement que les vars ne sont pas chiffrés ; utilisez les Worker secrets pour les identifiants et tokens. Consultez Secrets.

Une configuration délimitée par environnement pourrait ressembler à ceci :

name = "edge-gateway"
main = "src/index.ts"
compatibility_date = "2026-07-14"

[env.staging]
name = "edge-gateway-staging"
vars = { API_ORIGIN = "https://api.staging.example.com" }

[[env.staging.kv_namespaces]]
binding = "CONFIG"
id = "staging-namespace-id"

[env.production]
name = "edge-gateway-production"
vars = { API_ORIGIN = "https://api.example.com" }

[[env.production.kv_namespaces]]
binding = "CONFIG"
id = "production-namespace-id"

Les déclarations de bindings doivent correspondre à l'interface env du handler et les ressources cibles doivent exister dans le compte cible. Utilisez la documentation du type de ressource concerné lors de l'ajout de bindings ; la référence de configuration Wrangler liste la configuration des bindings et les règles d'héritage des environnements.

Définissez le secret de chaque environnement indépendamment. Une mise à jour de secret immédiate crée et déploie une version de Worker ; réservez-la donc à un environnement non progressif comme le staging :

wrangler secret put UPSTREAM_TOKEN --env staging

Pour un déploiement progressif en production, utilisez la commande consciente des versions dans le même workflow de release revu que le candidat, puis déployez cette version via le split approuvé :

wrangler versions secret put UPSTREAM_TOKEN --env production
wrangler versions deploy --env production

Cloudflare documente que les versions plus anciennes de Wrangler peuvent nécessiter --x-versions. Confirmez que la version installée prend en charge wrangler versions secret put avant la fenêtre de changement, sans quoi mettez à jour Wrangler plutôt que de retomber sur un wrangler secret put immédiat en production. Ne placez pas un secret de production dans une configuration preview, staging ou de dépôt. Traitez la rotation de secrets comme un changement opérationnel : déployez du code qui accepte à la fois les anciens et nouveaux identifiants si l'amont exige une rotation par étapes, puis retirez l'ancienne valeur après vérification.

Activer l'observabilité Workers avant d'en avoir besoin

Les Workers Logs ne sont pas activés par défaut pour un nouveau Worker. Ajoutez un bloc observability au fichier Wrangler et redéployez avant la fenêtre de changement, pas pendant un incident :

[observability]
enabled = true
head_sampling_rate = 1

[env.production.observability]
enabled = true
head_sampling_rate = 0.1

head_sampling_rate accepte une valeur de 0 à 1 et vaut 1 par défaut si omis. Acme Shop garde le staging à un échantillonnage complet, où chaque requête compte pour la porte d'acceptation, et abaisse l'échantillonnage de production une fois la route stable et à fort volume, pour maîtriser le coût des logs. Un taux plus bas ne doit pas faire perdre en visibilité sur les échecs : combinez l'échantillonnage en tête avec un Tail Worker ou un filtre Logpush qui transmet toujours les réponses non-2xx et les exceptions, afin qu'une erreur rare ne disparaisse jamais du dashboard dont dépend une porte de canari.

Le handler typé d'Acme Shop

Ce handler n'accepte que l'unique route de lecture publique et ne transmet à l'amont ni cookies, ni en-têtes d'autorisation, ni en-têtes client arbitraires. Il utilise un timeout borné et renvoie des erreurs génériques sûres ; le no-store explicite évite de créer par accident une politique de cache partagée dans le Worker.

export interface Env {
  API_ORIGIN: string
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url)

    if (url.pathname !== "/edge/catalog") return new Response("Not found", { status: 404 })
    if (request.method !== "GET") return new Response("Method not allowed", { status: 405 })

    const upstream = new URL("/catalog", env.API_ORIGIN)
    upstream.search = url.search

    try {
      const response = await fetch(upstream, {
        headers: { Accept: "application/json" },
        signal: AbortSignal.timeout(1_500),
      })

      if (!response.ok) return new Response("Catalogue temporarily unavailable", { status: 502 })

      return new Response(response.body, {
        headers: {
          "cache-control": "no-store",
          "content-type": response.headers.get("content-type") ?? "application/json",
        },
      })
    } catch {
      return new Response("Catalogue temporarily unavailable", { status: 503 })
    }
  },
} satisfies ExportedHandler<Env>

Utilisez une interface Env qui correspond à chaque binding déclaré, gardez l'origine de staging distincte de la production, et faites valider le handler par TypeScript avant de déployer. Si une future route nécessite un amont authentifié, utilisez un Worker secret et un contrat serveur-à-serveur étroitement scopé ; ne faites jamais transiter d'identifiants client par le Worker.

Étape 3 : déployer dans un environnement isolé

Exécutez d'abord les contrôles statiques et les tests applicatifs. Validez ensuite la configuration Wrangler résolue et déployez l'environnement staging :

wrangler deploy --env staging

Les environnements Wrangler permettent à un projet de déclarer des cibles de déploiement séparées. Confirmez le nom du worker déployé, le compte, les routes, bindings, compatibility date et tout paramètre propre à l'environnement dans la sortie de commande et le dashboard Cloudflare. Le guide des environnements explique ce qui est ou non hérité par les environnements nommés ; ne supposez pas qu'un binding ou une variable de production est automatiquement présent en staging.

Si le Worker est attaché à une route, vérifiez la précédence des routes et que le pattern de route est intentionnellement étroit. Un pattern large peut intercepter du trafic qui était auparavant servi par un autre Worker ou par l'origine. Pour les custom domains et les routes, utilisez la configuration de routage documentée.

Étape 4 : tester de manière sûre avant la production

Utilisez un hostname hors production ou une route de staging délibérément étroite. Exercez le chemin de requête de bout en bout, et non uniquement un test local du handler.

Testez au moins les éléments suivants :

• Les réponses de succès attendues, méthodes, en-têtes, comportement de cache et comportement CORS.
• Les identifiants absents ou invalides, entrées malformées et frontières d'autorisation.
• Les timeouts amont, échecs DNS, réponses 5xx et réponses de limitation de débit.
• Chaque chemin de binding, y compris le comportement lorsqu'une configuration optionnelle est absente.
• La correspondance des routes avec des URL représentatives proches de la production, y compris les chemins qui doivent contourner le Worker.
• Le comportement de réponse et de journalisation lorsqu'un secret ou binding requis est délibérément indisponible en staging.

Utilisez la commande suivante pour un retour local rapide :

wrangler dev

Ne traitez pas le développement local comme l'équivalent de la production. Cloudflare distingue les modes de développement local et distant dans Wrangler development ; les dépendances distantes, routes, bindings et la configuration du compte exigent toujours un test de déploiement dans un environnement.

Étape 5 : l'observabilité Workers en staging

Instrumentez le Worker avec des événements structurés non sensibles qui identifient la route, la classe de résultat, la dépendance amont et la version de déploiement. Évitez de journaliser les en-têtes d'autorisation, cookies, corps de requête, access tokens ou identifiants client.

Pendant la fenêtre de test, examinez :

• Le taux d'erreur Worker et les échantillons d'exception dans le dashboard.

• Le volume de requêtes et la distribution de statuts de réponse comparés au chemin connu comme bon.

• Le temps CPU et les autres signaux de ressources qui peuvent approcher les limites documentées.

• Les métriques de latence et d'erreur amont du service faisant autorité, car une réponse Worker réussie peut tout de même masquer un comportement d'origine dégradé.

• Inspectez les logs lorsqu'un diagnostic en direct au niveau des requêtes est nécessaire :

  wrangler tail --env staging
  

Cloudflare documente la télémétrie disponible et les workflows de tailing dans Observability. Conservez les métriques et logs dans votre plateforme d'observabilité centrale si le processus d'incident exige une rétention plus longue ou une corrélation avec les signaux d'origine.

Choisir où vit la télémétrie

L'observabilité Workers recouvre quatre mécanismes distincts, et choisir le mauvais pour la question posée gaspille la fenêtre d'observation :

• Workers Logs, dans le dashboard, une fois activés : le chemin le plus rapide vers une vue filtrée des invocations récentes d'un seul Worker, sans système externe.
• wrangler tail diffuse des événements en direct pendant un déploiement ou un incident ; c'est une session de diagnostic, pas de la rétention, et elle s'arrête au moment où le terminal se ferme.
• Logpush exporte en continu les Workers Trace Event Logs vers R2, S3 ou une destination tierce : le mécanisme à privilégier quand l'acceptation exige une rétention au-delà de la fenêtre du dashboard, ou des jointures avec des logs d'origine ou de WAF stockés ailleurs.
• L'export OpenTelemetry envoie les traces Workers via OTLP vers Grafana, Honeycomb ou Axiom : pertinent dès que le Worker de catalogue n'est qu'un saut dans une requête qui touche d'autres services et que l'unité d'analyse utile est la trace complète, pas les logs d'un Worker isolé.

Un tail en direct répond à « que se passe-t-il maintenant », Workers Logs répond à « qu'est-il arrivé récemment à ce Worker », et Logpush ou l'export OTel répondent à « qu'est-il arrivé sur l'ensemble du système pendant la fenêtre de rétention exigée par le processus d'incident ».

Étape 6 : exécuter un déploiement canari en périphérie

Déployez l'environnement de production uniquement après que le staging a satisfait ses critères d'acceptation :

wrangler deploy --env production

Pour un canari versionné, n'utilisez pas le déploiement immédiat ci-dessus pour le candidat. Le workflow de déploiement progressif de Cloudflare charge une version sans la déployer, puis crée un déploiement fractionné de façon interactive :

wrangler versions upload --env production
wrangler versions deploy --env production

Choisissez les identifiants de version connue comme bonne et candidate dans le déploiement interactif, commencez avec la plus petite exposition justifiée par le volume de trafic, et consignez les pourcentages choisis. Un split est évalué par requête par défaut, donc des requêtes consécutives peuvent atteindre des versions différentes. Gardez les changements d'API et de Durable Object rétro et anté-compatibles ; une migration de Durable Object ne peut pas être traitée en toute sécurité comme un rollback de déploiement progressif ordinaire.

Sortie Wrangler représentative pour un split de déploiement (identifiants de version raccourcis) :

Uploaded edge-gateway-production version: 3a0f...c91e
No deployment changed.

Deployment created
  95%  version 81d2...0a44  (known good)
   5%  version 3a0f...c91e  (candidate)

Préférez un mécanisme d'exposition limitée avant une bascule complète de route. Selon l'architecture, il peut s'agir d'un hostname canari dédié, d'une route à périmètre étroit, d'une cohorte contrôlée choisie par l'application ou de Worker versions and deployments Cloudflare lorsqu'ils sont disponibles pour le compte et le modèle de déploiement. N'annoncez pas une amélioration de latence fixe et ne supposez pas que la répartition du trafic dispense d'un monitoring fonctionnel ; l'emplacement du cache, le comportement d'origine, les chemins de code et la géographie client déterminent les résultats observés.

Automatiser le split pour un canari reproductible

Une invite interactive convient à une release ponctuelle ; un processus reproductible devrait scripter le split afin que version et pourcentages soient revus dans la fiche de changement. Une fois les deux identifiants connus, Wrangler accepte une forme non interactive :

wrangler versions deploy \
  81d2f0a1-3b7c-4e21-9a5d-000000000a44@95% \
  3a0fbb21-7c4d-4a6e-8b12-0000000c91e0@5% \
  --message "Canari catalogue Acme Shop, étape 1" \
  -y

Gardez le champ --message significatif : il devient une partie de l'historique de déploiement exposé par le dashboard et l'API, et c'est le plus rapide moyen pour un répondant d'astreinte de voir ce qui a changé. Générez cette commande depuis la fiche de release plutôt que de laisser le pourcentage d'exposition être tapé à la main.

Décalage de version, affinité et cas limites à état

Un split en pourcentage est évalué par requête par défaut, donc le même onglet peut atteindre la version connue comme bonne à une requête et le candidat à la suivante. Pour la lecture de catalogue sans état d'Acme Shop, c'est sans conséquence ; cela devient une classe de défaut dès qu'une route touche des sessions, des formulaires multi-étapes ou des assets à empreinte de contenu devant correspondre à la page HTML qui les référence. L'affinité de version de Cloudflare épingle un appelant à une seule version en hachant une valeur portée par l'en-tête Cloudflare-Workers-Version-Key — dérivée d'un cookie de session, d'un identifiant utilisateur ou de l'IP client — afin que ses requêtes consécutives restent sur une version jusqu'à basculer, sans retour en arrière sans rollback explicite. Elle se configure via une Transform Rule de zone sur une route contrôlée ; elle n'est pas disponible sur un simple hostname *.workers.dev sauf si l'en-tête est défini par le client ou un Worker amont.

Les Durable Objects introduisent une seconde forme de décalage. Chaque instance étant un acteur unique et global, les changements de code se propagent de façon éventuellement cohérente : une requête peut atteindre la nouvelle version du Worker alors que le Durable Object qu'elle appelle exécute encore l'ancienne, pendant une courte fenêtre. Un nouveau déploiement redémarre aussi chaque Durable Object touché, coupant tout WebSocket ouvert sur lui. Traitez un canari sur un Worker adossé à des Durable Objects comme une migration : confirmez la compatibilité du contrat RPC ou de stockage dans les deux sens avant l'exposition, et attendez-vous à des reconnexions client pendant la release.

Définissez des gates canaris explicites avant l'exposition :

• Aucune augmentation significative des exceptions Worker ou des réponses 5xx par rapport à la baseline.
• Aucun dépassement des seuils d'erreur ou de saturation du service amont.
• Aucune régression dans les contrôles synthétiques critiques ou les parcours utilisateur authentifiés.
• L'utilisation des ressources reste sous la marge de sécurité opérationnelle choisie à partir des limites Cloudflare actuelles.

Augmentez l'exposition uniquement après une période d'observation soutenue adaptée au volume de requêtes. Les services à faible volume nécessitent une observation plus longue ou du trafic synthétique pour produire des éléments significatifs.

Rollback

Préparez la commande de retour et le seuil de décision avant le déploiement de production. Pour une release basée sur une route, retirez ou restreignez la nouvelle route uniquement si cela rétablit le handler ou chemin d'origine connu comme bon. Pour un déploiement Worker versionné, rétablissez le trafic vers la version connue comme bonne via le workflow de déploiement pris en charge par Cloudflare. Consultez rollbacks for Worker versions pour la commande actuelle et le comportement du dashboard.

wrangler rollback [<version-id>] est le chemin versionné : il crée immédiatement un nouveau déploiement qui route 100 % du trafic vers la version nommée, ou vers la version précédente si elle est omise, en remplaçant tout split actif plutôt qu'en l'ajustant. Il ne touche pas aux ressources liées — KV, R2, D1, queues et secrets restent tels que configurés — donc il n'est sûr contre une dérive de données que si la forme attendue par l'ancien code n'a pas changé. Cloudflare bloque le rollback si une migration de Durable Object a eu lieu entre le déploiement actif et la cible, ou si celle-ci se lie à une ressource qui n'existe plus ; traitez ces deux cas comme un correctif en avant, pas un rollback. Seules les 100 versions publiées les plus récentes restent éligibles, donc vérifiez qu'une version de repli n'est pas sortie de cette fenêtre sur un Worker qui déploie fréquemment. Pour un runbook scripté, passez un message explicite afin de sauter la confirmation interactive :

wrangler rollback 81d2f0a1-3b7c-4e21-9a5d-000000000a44 \
  --message "Rollback catalogue Acme Shop : gate de taux d'erreur du canari franchie"

Après le rollback :

1. Confirmez que le chemin connu comme bon reçoit les requêtes.
2. Réexécutez les contrôles synthétiques et des endpoints représentatifs.
3. Continuez d'observer les erreurs Worker et origine jusqu'à leur retour à la baseline.
4. Conservez l'identifiant du déploiement échoué, le diff de configuration, les logs et la chronologie pour la revue d'incident.

N'utilisez pas un rollback comme substitut à une réparation de données. Si la release a produit des effets à état, rapprochez-les dans le système de référence en utilisant la procédure de récupération documentée du workflow métier.

Pièges fréquents

• Traiter vars comme un stockage de secrets. Ce sont des configurations, pas du matériel secret chiffré.
• Déployer un Worker avant d'avoir vérifié que chaque environnement définit ses propres bindings et secrets requis.
• Utiliser un pattern de route qui capture involontairement des hostnames ou chemins non liés.
• Tester uniquement avec wrangler dev et manquer le routage, les bindings ou le comportement réseau amont au niveau du compte.
• Journaliser des données de requête sensibles en tentant de déboguer un incident.
• Supposer que l'edge peut rendre atomique un workflow à état entre systèmes externes.
• Effectuer un changement global sans version connue comme bonne, gate d'exposition ou responsable de rollback.
• Laisser un taux d'échantillonnage de logs trop bas masquer les échecs qu'un dashboard de canari est censé révéler.

Dépannage

Réserves techniques

Le comportement Worker dépend du plan Cloudflare, de la compatibility date, des produits activés, de la configuration du compte et de la région précise ainsi que du chemin de dépendance qui sert une requête. Consultez les limites et la documentation produit Cloudflare actuelles lors de chaque évolution matérielle de conception ou de plateforme. L'exécution edge peut réduire le travail à l'origine pour des requêtes adaptées, mais elle ne garantit pas une latence, disponibilité ou cohérence end-to-end inférieure pour chaque requête.

Sources principales

• Cloudflare Workers limits
• Cloudflare Wrangler configuration
• Cloudflare Wrangler environments
• Cloudflare Workers secrets
• Cloudflare Workers observability
• Cloudflare Worker versions, deployments, and rollbacks
• Cloudflare Workers gradual deployments and version affinity
• Cloudflare Workers Logs configuration