Configuration Wrangler Globale

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ôt

├── 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 service

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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ées

• 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
• 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
• Fichiers concernés :
  • wrangler.toml (racine, optionnel)
  • package.json (scripts monorepo)
  • .github/workflows/deploy-workers.yml

14. Historique des modifications

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

---

**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)