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.

Prérequis

Avant de modifier le trafic, mettez en place les éléments suivants :

• 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.

É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.

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. Par exemple :

wrangler secret put UPSTREAM_TOKEN --env staging
wrangler secret put UPSTREAM_TOKEN --env 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.

É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 wrangler dev pour un retour local rapide, mais ne le traitez pas 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 : observer le déploiement 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é.
• Les logs avec wrangler tail --env staging lorsqu'un diagnostic en direct au niveau des requêtes est nécessaire.

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.

Étape 6 : déployer en canari la version de production

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

wrangler deploy --env production

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.

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.

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.

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