Configuration Wrangler Globale
Configuration Wrangler Globale
Documentation technique
Type de ressource : Configuration Wrangler (Monorepo / Services Cloudflare)
Fichier source :wrangler.toml(racine) etservices/[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.md2.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)
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)
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)
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é)
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)
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)
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
# Injection des secrets pour le service middlewarewrangler secret put SANITY_PREVIEW_SECRET --env production --config services/middleware/wrangler.tomlwrangler secret put SANITY_PREVIEW_SECRET --env staging --config services/middleware/wrangler.toml
# Injection des secrets pour le service form-handlerwrangler secret put TURNSTILE_SECRET_KEY --env production --config services/form-handler/wrangler.tomlwrangler secret put CRM_API_KEY --env production --config services/form-handler/wrangler.toml
# Injection des secrets pour le service cms-webhook-receiverwrangler secret put SANITY_WEBHOOK_SECRET --env production --config services/cms-webhook-receiver/wrangler.toml
# Injection des secrets pour le service media-uploadwrangler secret put R2_ACCESS_KEY_ID --env production --config services/media-upload/wrangler.tomlwrangler secret put R2_SECRET_ACCESS_KEY --env production --config services/media-upload/wrangler.tomlwrangler secret put CLOUDFLARE_STREAM_API_TOKEN --env production --config services/media-upload/wrangler.toml
# Injection des secrets pour le service media-cleanupwrangler secret put SANITY_READ_TOKEN --env production --config services/media-cleanup/wrangler.toml
# Injection des secrets pour le service sanity-backupwrangler secret put SANITY_ADMIN_TOKEN --env production --config services/sanity-backup/wrangler.toml4.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
# Liste des secrets d'un servicewrangler secret list --config services/form-handler/wrangler.toml --env production
# Suppression d'un secretwrangler secret delete SECRET_NAME --config services/form-handler/wrangler.toml --env production5. 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
maindéclenche le déploiement en production - ✅ La branche
stagingdé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
# Création des namespaces KVwrangler kv:namespace create "WEBHOOK_LOCK_KV" --config services/cms-webhook-receiver/wrangler.toml --env productionwrangler kv:namespace create "WEBHOOK_LOCK_KV" --config services/cms-webhook-receiver/wrangler.toml --env staging
# Création des buckets R2wrangler r2 bucket create pub-mediaswrangler r2 bucket create pub-medias-stagingwrangler r2 bucket create backups-sanity
# Création des Queueswrangler queues create form-submissions-queue --env productionwrangler queues create form-submissions-queue --env staging7.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
name: Deploy Cloudflare Workerson: 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
# Liste des déploiementswrangler deployments list --config services/form-handler/wrangler.toml
# Rollback vers une version précédentewrangler deployments rollback --deployment-id=[id] --config services/form-handler/wrangler.toml8.3. Tests manuels
# Test local d'un servicenpm run dev:form-handler
# Test d'un Cron Triggerwrangler dev --config services/media-cleanup/wrangler.toml --test-scheduled
# Test d'un endpointcurl -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
# Logs d'un service spécifiquewrangler tail form-handler --env production
# Logs avec filtrewrangler tail cms-webhook-receiver --env production --format pretty
# Logs de tous les services (via Cloudflare Dashboard)# Dashboard → Workers & Pages → [Service] → Logs9.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
# Configuration Logpush (via Dashboard ou API)# Dashboard → Workers & Pages → [Service] → Logs → Logpush# Destination : Datadog / Axiom / S310. 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
# Vérification de la configurationwrangler deploy --dry-run --config services/form-handler/wrangler.toml
# Inspection des bindingswrangler kv:key list --binding=WEBHOOK_LOCK_KV --config services/cms-webhook-receiver/wrangler.toml
# Inspection des objets R2wrangler r2 object list pub-medias --prefix medias/
# Test d'un Cron Triggerwrangler dev --config services/media-cleanup/wrangler.toml --test-scheduled11. Bonnes pratiques
11.1. Architecture
- ✅ Séparer la configuration par service (un
wrangler.tomlpar Worker) - ✅ Centraliser les scripts de déploiement dans le
package.jsonracine - ✅ Utiliser des environnements distincts (production/staging/preview)
- ✅ Documenter les bindings et secrets dans ce fichier
- ✅ Versionner les
wrangler.tomldans Git (sauf les secrets)
11.2. Sécurité
- ✅ Ne jamais commiter les secrets dans Git
- ✅ Utiliser
wrangler secret putpour 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_dateré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.tomlservices/form-handler/wrangler.tomlservices/cms-webhook-receiver/wrangler.tomlservices/media-upload/wrangler.tomlservices/media-cleanup/wrangler.tomlservices/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)