Skip to content

Configuration Wrangler Globale

Configuration Wrangler Globale

Documentation technique

Type de ressource : Configuration Wrangler (Monorepo / Services Cloudflare)
Fichier source : wrangler.toml (racine) et services/[worker-name]/wrangler.toml
Statut : [Actif / Déprécié / En développement]

1. Vue d’ensemble

1.1. Description

[Description concise du rôle de cette configuration Wrangler dans l’orchestration des services Cloudflare du monorepo]

1.2. Objectif

  • [Objectif principal : ex. centraliser la configuration de déploiement de tous les Workers et bindings du monorepo]
  • [Bénéfice pour l’architecture : ex. cohérence entre environnements, gestion unifiée des secrets]

1.3. Périmètre concerné

  • Services couverts : [Liste : middleware, form-handler, cms-webhook-receiver, media-upload, media-cleanup, sanity-backup]
  • Environnements : [Production / Staging / Preview]
  • Type de configuration : [Wrangler.toml / Secrets / Variables d’environnement / Bindings]

2. Architecture du Monorepo

2.1. Structure du dépôt1/2

2.1. Structure du dépôt2/2

├── apps/
│ └── web/ # Projet Front-End Astro (Couche 02)
├── services/
│ ├── middleware/ # Worker Middleware Global
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── wrangler.toml
│ │ └── package.json
│ ├── form-handler/ # Microservice formulaires
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── wrangler.toml
│ │ └── package.json
│ ├── cms-webhook-receiver/ # Microservice webhooks
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── wrangler.toml
│ │ └── package.json
│ ├── media-upload/ # Microservice upload présigné
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── wrangler.toml
│ │ └── package.json
│ ├── media-cleanup/ # Microservice cron nettoyage
│ │ ├── src/
│ │ │ └── index.ts
│ │ ├── wrangler.toml
│ │ └── package.json
│ └── sanity-backup/ # Microservice cron sauvegarde
│ ├── src/
│ │ └── index.ts
│ ├── wrangler.toml
│ └── package.json
├── package.json # Scripts monorepo
├── wrangler.toml # Configuration racine (optionnelle)
└── README.md

2.2. Composants impliqués

Composant Rôle Type
wrangler.toml (racine) Configuration globale (optionnelle) Config
services/*/wrangler.toml Configuration par service Config
Cloudflare Secrets Variables sensibles injectées Runtime
Cloudflare Dashboard Gestion manuelle des ressources UI
CI/CD Pipeline Déploiement automatisé Infrastructure

3. Configuration par service

3.1. Worker middleware (Middleware Global)

services/middleware/wrangler.toml
name = "global-middleware"
main = "src/index.ts"
compatibility_date = "2026-09-01"
compatibility_flags = ["nodejs_compat"]
# Variables non-sensibles
[vars]
ALLOWED_ORIGIN = "https://votresite.com"
# Secrets (injectés via wrangler secret put)
# - SANITY_PREVIEW_SECRET
[env.production]
vars = { ALLOWED_ORIGIN = "https://votresite.com" }
[env.staging]
vars = { ALLOWED_ORIGIN = "https://staging.votresite.com" }

3.2. Worker form-handler (Traitement des Formulaires)

services/form-handler/wrangler.toml
name = "form-handler"
main = "src/index.ts"
compatibility_date = "2026-09-01"
[vars]
CRM_ENDPOINT_URL = "https://api.moncrm.com/v1/leads"
# Queue Producer
[[queues.producers]]
queue = "form-submissions-queue"
binding = "SUBMISSIONS_QUEUE"
# Secrets (injectés via wrangler secret put)
# - TURNSTILE_SECRET_KEY
# - CRM_API_KEY
[env.production]
vars = { CRM_ENDPOINT_URL = "https://api.moncrm.com/v1/leads" }
[env.staging]
vars = { CRM_ENDPOINT_URL = "https://staging-api.moncrm.com/v1/leads" }

3.3. Worker cms-webhook-receiver (Récepteur Webhooks)

services/cms-webhook-receiver/wrangler.toml
name = "cms-webhook-receiver"
main = "src/index.ts"
compatibility_date = "2026-09-01"
[vars]
BUILD_HOOK_URL = "https://api.cloudflare.com/client/v4/accounts/XXX/pages/projects/YYY/deploy-hooks/ZZZ"
# KV Namespace (Debouncing)
[[kv_namespaces]]
binding = "WEBHOOK_LOCK_KV"
id = "your-kv-namespace-id"
preview_id = "your-preview-kv-namespace-id"
# Secrets (injectés via wrangler secret put)
# - SANITY_WEBHOOK_SECRET
[env.production]
vars = { BUILD_HOOK_URL = "https://api.cloudflare.com/client/v4/accounts/XXX/pages/projects/YYY/deploy-hooks/ZZZ" }
[env.staging]
vars = { BUILD_HOOK_URL = "https://api.cloudflare.com/client/v4/accounts/XXX/pages/projects/YYY-staging/deploy-hooks/ZZZ" }

3.4. Worker media-upload (Upload Présigné)

services/media-upload/wrangler.toml
name = "media-upload"
main = "src/index.ts"
compatibility_date = "2026-09-01"
[vars]
R2_ACCOUNT_ID = "your-account-id"
R2_BUCKET_NAME = "pub-medias"
R2_PUBLIC_DOMAIN = "pub-medias.votredomaine.com"
# R2 Bucket Binding
[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "pub-medias"
preview_bucket_name = "pub-medias-staging"
# Secrets (injectés via wrangler secret put)
# - R2_ACCESS_KEY_ID
# - R2_SECRET_ACCESS_KEY
# - CLOUDFLARE_STREAM_API_TOKEN
# - CLOUDFLARE_ACCOUNT_ID
[env.production]
vars = { R2_BUCKET_NAME = "pub-medias" }
[env.staging]
vars = { R2_BUCKET_NAME = "pub-medias-staging" }

3.5. Worker media-cleanup (Nettoyage Cron)

services/media-cleanup/wrangler.toml
name = "media-cleanup"
main = "src/index.ts"
compatibility_date = "2026-09-01"
[vars]
SANITY_PROJECT_ID = "your-project-id"
SANITY_DATASET = "production"
R2_PUBLIC_DOMAIN = "pub-medias.votredomaine.com"
# R2 Bucket Binding
[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "pub-medias"
# Cron Trigger (hebdomadaire, dimanche 3h00)
[triggers]
crons = ["0 3 * * 0"]
# Secrets (injectés via wrangler secret put)
# - SANITY_READ_TOKEN
[env.production]
vars = { SANITY_DATASET = "production" }
[env.staging]
vars = { SANITY_DATASET = "staging" }

3.6. Worker sanity-backup (Backup Cron)

services/sanity-backup/wrangler.toml
name = "sanity-backup"
main = "src/index.ts"
compatibility_date = "2026-09-01"
[vars]
SANITY_PROJECT_ID = "your-project-id"
SANITY_DATASET = "production"
# R2 Bucket Binding (Bucket dédié aux backups)
[[r2_buckets]]
binding = "R2_BACKUP_BUCKET"
bucket_name = "backups-sanity"
# Cron Trigger (quotidien, 2h00)
[triggers]
crons = ["0 2 * * *"]
# Secrets (injectés via wrangler secret put)
# - SANITY_ADMIN_TOKEN
[env.production]
vars = { SANITY_DATASET = "production" }
[env.staging]
vars = { SANITY_DATASET = "staging" }

4. Gestion des secrets

4.1. Matrice des secrets par service1/2

Service Secret Description Rotation
middleware SANITY_PREVIEW_SECRET Secret de validation preview 90 jours
form-handler TURNSTILE_SECRET_KEY Clé secrète Turnstile 90 jours
form-handler CRM_API_KEY Clé API CRM 90 jours
cms-webhook-receiver SANITY_WEBHOOK_SECRET Secret validation HMAC webhook 90 jours
media-upload R2_ACCESS_KEY_ID Clé d’accès R2 90 jours

4.1. Matrice des secrets par service2/2

Service Secret Description Rotation
media-upload R2_SECRET_ACCESS_KEY Clé secrète R2 90 jours
media-upload CLOUDFLARE_STREAM_API_TOKEN Token API Stream 90 jours
media-cleanup SANITY_READ_TOKEN Token lecture Sanity 90 jours
sanity-backup SANITY_ADMIN_TOKEN Token admin Sanity (export) 90 jours

4.2. Commandes d’injection

Terminal window
# Injection des secrets pour le service middleware
wrangler secret put SANITY_PREVIEW_SECRET --env production --config services/middleware/wrangler.toml
wrangler secret put SANITY_PREVIEW_SECRET --env staging --config services/middleware/wrangler.toml
# Injection des secrets pour le service form-handler
wrangler secret put TURNSTILE_SECRET_KEY --env production --config services/form-handler/wrangler.toml
wrangler secret put CRM_API_KEY --env production --config services/form-handler/wrangler.toml
# Injection des secrets pour le service cms-webhook-receiver
wrangler secret put SANITY_WEBHOOK_SECRET --env production --config services/cms-webhook-receiver/wrangler.toml
# Injection des secrets pour le service media-upload
wrangler secret put R2_ACCESS_KEY_ID --env production --config services/media-upload/wrangler.toml
wrangler secret put R2_SECRET_ACCESS_KEY --env production --config services/media-upload/wrangler.toml
wrangler secret put CLOUDFLARE_STREAM_API_TOKEN --env production --config services/media-upload/wrangler.toml
# Injection des secrets pour le service media-cleanup
wrangler secret put SANITY_READ_TOKEN --env production --config services/media-cleanup/wrangler.toml
# Injection des secrets pour le service sanity-backup
wrangler secret put SANITY_ADMIN_TOKEN --env production --config services/sanity-backup/wrangler.toml

4.3. Règles de sécurité

  • ✅ Les secrets ne sont jamais commités dans Git
  • ✅ Les secrets sont injectés via wrangler secret put (chiffrés par Cloudflare)
  • ✅ Rotation recommandée tous les 90 jours
  • ✅ Les secrets sont spécifiques à chaque environnement (production/staging)
  • ✅ Les secrets ne sont jamais loggés dans les Workers

4.4. Vérification des secrets

Terminal window
# Liste des secrets d'un service
wrangler secret list --config services/form-handler/wrangler.toml --env production
# Suppression d'un secret
wrangler secret delete SECRET_NAME --config services/form-handler/wrangler.toml --env production

5. Scripts npm du monorepo

5.1. Scripts de déploiement

// package.json (racine)
{
"name": "monorepo-cloudflare",
"private": true,
"scripts": {
"deploy:all": "npm run deploy:middleware && npm run deploy:form-handler && npm run deploy:cms-webhook-receiver && npm run deploy:media-upload && npm run deploy:media-cleanup && npm run deploy:sanity-backup",
"deploy:middleware": "wrangler deploy --config services/middleware/wrangler.toml --env production",
"deploy:form-handler": "wrangler deploy --config services/form-handler/wrangler.toml --env production",
"deploy:cms-webhook-receiver": "wrangler deploy --config services/cms-webhook-receiver/wrangler.toml --env production",
"deploy:media-upload": "wrangler deploy --config services/media-upload/wrangler.toml --env production",
"deploy:media-cleanup": "wrangler deploy --config services/media-cleanup/wrangler.toml --env production",
"deploy:sanity-backup": "wrangler deploy --config services/sanity-backup/wrangler.toml --env production",
"deploy:staging": "npm run deploy:middleware:staging && npm run deploy:form-handler:staging && ...",
"deploy:middleware:staging": "wrangler deploy --config services/middleware/wrangler.toml --env staging",
"deploy:form-handler:staging": "wrangler deploy --config services/form-handler/wrangler.toml --env staging",
"dev:middleware": "wrangler dev --config services/middleware/wrangler.toml",
"dev:form-handler": "wrangler dev --config services/form-handler/wrangler.toml",
"dev:cms-webhook-receiver": "wrangler dev --config services/cms-webhook-receiver/wrangler.toml",
"dev:media-upload": "wrangler dev --config services/media-upload/wrangler.toml",
"dev:media-cleanup": "wrangler dev --config services/media-cleanup/wrangler.toml --test-scheduled",
"dev:sanity-backup": "wrangler dev --config services/sanity-backup/wrangler.toml --test-scheduled"
}
}

5.2. Scripts de gestion des secrets

// package.json (racine) - suite
{
"scripts": {
"secrets:list": "wrangler secret list --config services/form-handler/wrangler.toml",
"secrets:rotate": "node scripts/rotate-secrets.js",
"secrets:audit": "node scripts/audit-secrets.js"
}
}

6. Configuration des environnements

6.1. Matrice des environnements

Environnement Usage URL Déclenchement
production Production publique https://votresite.com Merge sur main
staging Pré-production https://staging.votresite.com Push sur staging
preview Preview par PR https://[pr-id].preview.votresite.com Pull Request

6.2. Variables d’environnement par environnement

Variable Production Staging Preview
CRM_ENDPOINT_URL https://api.moncrm.com/v1/leads https://staging-api.moncrm.com/v1/leads https://staging-api.moncrm.com/v1/leads
R2_BUCKET_NAME pub-medias pub-medias-staging pub-medias-preview
SANITY_DATASET production staging staging
ALLOWED_ORIGIN https://votresite.com https://staging.votresite.com https://*.preview.votresite.com
BUILD_HOOK_URL [URL prod] [URL staging] -

6.3. Règles de déploiement

  • ✅ La branche main déclenche le déploiement en production
  • ✅ La branche staging déclenche le déploiement en staging
  • ✅ Les Pull Requests déclenchent des environnements de preview éphémères
  • ✅ Les secrets sont spécifiques à chaque environnement
  • ✅ Les bindings (KV, R2, Queue) peuvent être partagés ou isolés selon le besoin

7. Bindings Cloudflare

7.1. Matrice des bindings par service

Service KV R2 Queue Service
middleware - - - -
form-handler - - SUBMISSIONS_QUEUE -
cms-webhook-receiver WEBHOOK_LOCK_KV - - -
media-upload - R2_BUCKET - -
media-cleanup - R2_BUCKET - -
sanity-backup - R2_BACKUP_BUCKET - -

7.2. Création des ressources

Terminal window
# Création des namespaces KV
wrangler kv:namespace create "WEBHOOK_LOCK_KV" --config services/cms-webhook-receiver/wrangler.toml --env production
wrangler kv:namespace create "WEBHOOK_LOCK_KV" --config services/cms-webhook-receiver/wrangler.toml --env staging
# Création des buckets R2
wrangler r2 bucket create pub-medias
wrangler r2 bucket create pub-medias-staging
wrangler r2 bucket create backups-sanity
# Création des Queues
wrangler queues create form-submissions-queue --env production
wrangler queues create form-submissions-queue --env staging

7.3. Lifecycle Rules R2

Bucket Règle Action Rétention
pub-medias Suppression temp/ Delete 7 jours
backups-sanity Purge automatique Delete 30 jours

8. CI/CD et déploiement

8.1. Pipeline de déploiement

.github/workflows/deploy-workers.yml
name: Deploy Cloudflare Workers
on:
push:
branches: [main, staging]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Deploy to Staging
if: github.ref == 'refs/heads/staging'
run: npm run deploy:staging
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
- name: Deploy to Production
if: github.ref == 'refs/heads/main'
run: npm run deploy:all
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

8.2. Rollback

Terminal window
# Liste des déploiements
wrangler deployments list --config services/form-handler/wrangler.toml
# Rollback vers une version précédente
wrangler deployments rollback --deployment-id=[id] --config services/form-handler/wrangler.toml

8.3. Tests manuels

Terminal window
# Test local d'un service
npm run dev:form-handler
# Test d'un Cron Trigger
wrangler dev --config services/media-cleanup/wrangler.toml --test-scheduled
# Test d'un endpoint
curl -X POST http://localhost:8787/ \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "message": "Test"}'

9. Monitoring et observabilité

9.1. Logs en temps réel

Terminal window
# Logs d'un service spécifique
wrangler tail form-handler --env production
# Logs avec filtre
wrangler tail cms-webhook-receiver --env production --format pretty
# Logs de tous les services (via Cloudflare Dashboard)
# Dashboard → Workers & Pages → [Service] → Logs

9.2. Métriques clés

Service Métrique Seuil d’alerte Canal
middleware Taux d’erreur 5xx > 1% sur 5 min PagerDuty
form-handler Échecs CRM > 2% sur 5 min Slack
cms-webhook-receiver Signatures invalides > 5 consécutifs Email Sécurité
media-cleanup Safety Lock déclenché 1 événement Slack
sanity-backup Échec du Cron 1 échec PagerDuty

9.3. Cloudflare Logpush

Terminal window
# Configuration Logpush (via Dashboard ou API)
# Dashboard → Workers & Pages → [Service] → Logs → Logpush
# Destination : Datadog / Axiom / S3

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme Cause probable Solution
“Binding not found” Binding mal configuré Vérifier le wrangler.toml et redéployer
“Secret not found” Secret non injecté Exécuter wrangler secret put
“Service unavailable” Worker non déployé Vérifier le déploiement avec wrangler deployments list
Cron non déclenché Configuration triggers.crons incorrecte Vérifier la syntaxe cron (5 champs)
Erreur de compatibilité compatibility_date trop ancien Mettre à jour vers 2026-09-01
Erreur de mémoire (OOM) Chargement de gros fichiers en RAM Utiliser le streaming HTTP

10.2. Commandes de debug

Terminal window
# Vérification de la configuration
wrangler deploy --dry-run --config services/form-handler/wrangler.toml
# Inspection des bindings
wrangler kv:key list --binding=WEBHOOK_LOCK_KV --config services/cms-webhook-receiver/wrangler.toml
# Inspection des objets R2
wrangler r2 object list pub-medias --prefix medias/
# Test d'un Cron Trigger
wrangler dev --config services/media-cleanup/wrangler.toml --test-scheduled

11. Bonnes pratiques

11.1. Architecture

  • ✅ Séparer la configuration par service (un wrangler.toml par Worker)
  • ✅ Centraliser les scripts de déploiement dans le package.json racine
  • ✅ Utiliser des environnements distincts (production/staging/preview)
  • ✅ Documenter les bindings et secrets dans ce fichier
  • ✅ Versionner les wrangler.toml dans Git (sauf les secrets)

11.2. Sécurité

  • ✅ Ne jamais commiter les secrets dans Git
  • ✅ Utiliser wrangler secret put pour injecter les secrets
  • ✅ Rotation régulière des secrets (tous les 90 jours)
  • ✅ Valider les permissions des tokens API (principe du moindre privilège)
  • ✅ Auditer les accès aux ressources Cloudflare

11.3. Performance

  • ✅ Utiliser compatibility_date récent pour bénéficier des optimisations
  • ✅ Minimiser le nombre de bindings par Worker
  • ✅ Utiliser le streaming HTTP pour les gros volumes
  • ✅ Mettre en cache les données fréquemment lues (KV)

11.4. Maintenance

  • ✅ Documenter les changements de configuration dans ce fichier
  • ✅ Tester les déploiements en staging avant production
  • ✅ Surveiller les métriques après chaque déploiement
  • ✅ Automatiser les déploiements via CI/CD
  • ✅ Maintenir un rollback plan en cas de problème

12. Évolutions et roadmap

12.1. Améliorations planifiées

  • [Évolution 1 : ex. Migration vers Wrangler v4]
  • [Évolution 2 : ex. Ajout de Durable Objects pour les sessions]
  • [Évolution 3 : ex. Implémentation de Workflows pour les traitements longs]
  • [Évolution 4 : ex. Centralisation des logs via Logpush vers Datadog]

12.2. Limitations connues

  • ❌ Les secrets ne peuvent pas être versionnés dans Git
  • ❌ Les bindings KV ont des limites de taille (25 MB par clé)
  • ❌ Les Cron Triggers ont une granularité minimale d’une minute
  • ❌ Les Queues ont une limite de 10 MB par message

13. Ressources liées1/3

  • Documentation Wrangler : CLI Reference
  • Documentation Wrangler : Configuration
  • Documentation Cloudflare Workers : Getting Started
  • DAT L3 : §6 - Structure Monorepo, Wrangler & Configuration
  • DAT L3 : §7 - Monitoring, Observabilité & Alerting

13. Ressources liées2/3

  • Services concernés :
    • services/middleware/wrangler.toml
    • services/form-handler/wrangler.toml
    • services/cms-webhook-receiver/wrangler.toml
    • services/media-upload/wrangler.toml
    • services/media-cleanup/wrangler.toml
    • services/sanity-backup/wrangler.toml

13. Ressources liées3/3

  • Fichiers concernés :
    • wrangler.toml (racine, optionnel)
    • package.json (scripts monorepo)
    • .github/workflows/deploy-workers.yml

14. Historique des modifications1/2

Date Version Description Auteur
YYYY-MM-DD 1.0 Création initiale [Nom]
YYYY-MM-DD 1.1 [Modification] [Nom]

14. Historique des modifications2/2

---
**Points clés de ce template :**
- Documente la configuration complète du monorepo Cloudflare (tous les Workers)
- Détaille la structure du dépôt et l'organisation par service
- Inclut la matrice complète des secrets et leur injection
- Fournit les scripts npm pour le déploiement et le développement local
- Couvre la gestion des environnements (production/staging/preview)
- Documente les bindings Cloudflare (KV, R2, Queue) par service
- Inclut le pipeline CI/CD et les commandes de rollback
- Sépare clairement les bonnes pratiques par catégorie (architecture, sécurité, performance, maintenance)
Switch to normal mode

Contents