Cloudflare API: gestire DNS e configurazione da script

L'API Cloudflare è una REST API completa che permette di gestire ogni aspetto della configurazione: DNS records, zone, Page Rules, Workers, Pages, certificati, analytics, security. È fondamentale per automatizzazione, CI/CD pipeline, gestione multi-zona, integrazione con tool DevOps come Terraform, Ansible, Pulumi. Disponibile gratuitamente, supporta autenticazione moderna via API Token con scope granulari per security.

API Token vs Global API Key

Cloudflare offre due metodi di autenticazione. Global API Key: legacy, ha accesso a tutto, ad alto rischio se compromesso. API Token: moderno, scope granulare (zona specifica, permissions specifici), rotabile facilmente, scadenza opzionale. La raccomandazione è sempre API Token per qualsiasi automazione: principio del least privilege, isolation tra contesti, audit log dettagliato.

Procedura passo-passo

1. Vai su My Profile → API Tokens.
2. Clicca Create Token.
3. Scegli template (es. "Edit Zone DNS") o custom.
4. Definisci permissions: Zone → DNS → Edit.
5. Definisci zone resources: solo zona specifica o tutte le tue zone.
6. Opzionalmente imposta IP whitelist e TTL del token.
7. Salva e copia il token (visibile UNA sola volta).
8. Testa con curl: curl -H "Authorization: Bearer TOKEN" https://api.cloudflare.com/client/v4/user/tokens/verify.
9. Risposta deve includere success: true.
10. Conserva il token in secrets manager (Vault, AWS Secrets, env var).

Esempi di chiamate comuni

Lista record DNS: GET /zones/{ZONE_ID}/dns_records. Crea record A: POST /zones/{ZONE_ID}/dns_records con body {"type":"A","name":"sub","content":"1.2.3.4","ttl":1,"proxied":true}. Update record: PUT /zones/{ZONE_ID}/dns_records/{RECORD_ID}. Delete: DELETE /zones/{ZONE_ID}/dns_records/{RECORD_ID}. Purge cache: POST /zones/{ZONE_ID}/purge_cache con {"purge_everything":true}.

Script bash di esempio

Esempio di script che aggiorna un record A con l'IP corrente (utile per dynamic DNS):

1. Ottieni IP pubblico corrente: IP=$(curl -s https://api.ipify.org).
2. Ottieni record ID: curl -s -H "Authorization: Bearer $TOKEN" "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?name=home.tuosito.it".
3. Estrai ID con jq: RECORD_ID=$(... | jq -r '.result[0].id').
4. Aggiorna record: curl -X PUT -H "Authorization: Bearer $TOKEN" -d '{"type":"A","name":"home","content":"'$IP'","ttl":120,"proxied":true}' https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID.
5. Verifica response per success: true.
6. Schedula via cron: */5 * * * * /opt/scripts/update_dns.sh.

Terraform e Pulumi integration

Per gestione enterprise multi-zona consider Terraform provider Cloudflare o Pulumi. Permettono di definire infrastruttura DNS in codice versionato, applicare modifiche con plan/apply, rollback semplice. Esempio Terraform: resource "cloudflare_record" "example" { zone_id = ... type = "A" name = "www" value = "1.2.3.4" }. Best practice: separa state per environment, abbina con CI/CD pipeline.

Errori comuni e come risolverli

• 401 Unauthorized: token errato o scaduto. Rigenera token.
• 403 Forbidden: token senza scope sufficiente. Aggiungi permission.
• 429 Rate limit: API ha limit 1200 req/5min per token. Aggiungi backoff exponential.
• JSON malformato: verifica content-type e syntax.
• Zone ID sbagliato: vai su Dashboard → Zone → Overview → API per il valore corretto.

API GraphQL Analytics

Per analytics in volume Cloudflare espone GraphQL Analytics API: query potenti su metriche HTTP, DNS, security, performance. Esempio: query top 10 paths con MISS rate in 24h. Permette di costruire dashboard custom in Grafana/Looker/Metabase. Endpoint: https://api.cloudflare.com/client/v4/graphql. La documentazione include sample query per la maggior parte dei use case comuni.

Webhooks e notification

Cloudflare supporta Notification API per ricevere webhook su eventi: DDoS attack, certificate change, billing alerts, health check failure. Configura endpoint in Notifications, registra webhook URL del tuo sistema (Slack, PagerDuty, custom). Cloudflare invierà POST JSON con dettagli evento. Permette automazione completa di response a eventi infrastrutturali.

Domande frequenti

D: API è gratuita?
R: Sì su tutti i piani, con rate limit di 1200 req/5min per token.

D: Posso usare API per Workers?
R: Sì, ma Wrangler CLI è più conveniente per Workers.

D: Token può essere scope-limited per IP?
R: Sì, IP whitelist nelle restrictions del token.

D: Documentazione completa?
R: developers.cloudflare.com/api.

Considerazioni operative finali

Quando applichi una configurazione di questo tipo in produzione è sempre buona norma seguire un'approccio incrementale: parti con un test su staging, monitora gli effetti per qualche giorno, poi estendi gradualmente al traffico live. La rete Cloudflare elabora ogni cambiamento in pochi secondi a livello globale, quindi le modifiche sono effettive quasi immediatamente, ma gli effetti collaterali su utenti reali possono richiedere ore o giorni per emergere. Annota nel runbook interno data, motivo e parametri di ogni modifica significativa. Una documentazione precisa accelera enormemente il troubleshooting futuro e facilita il passaggio di consegne tra membri del team.

Vale anche la pena ricordare che Cloudflare aggiorna frequentemente l'interfaccia del dashboard e le posizioni delle voci di menu. La logica e le funzionalità descritte in questa guida restano valide, ma il percorso esatto per raggiungere ogni opzione può variare leggermente nel tempo. In caso di difficoltà a trovare una specifica voce, utilizza la barra di ricerca interna del dashboard oppure consulta la documentazione ufficiale aggiornata. La community Cloudflare sul forum ufficiale e su Stack Overflow è inoltre molto attiva e offre spesso risposte rapide a problemi specifici di configurazione.

Per progetti complessi che coinvolgono più servizi Cloudflare contemporaneamente (CDN, Workers, WAF, Access, R2) conviene strutturare la configurazione come codice tramite Terraform o Pulumi. Questo permette versioning, code review, rollback atomici e deploy ripetibili tra environment. Per team con esigenze più semplici la gestione manuale via dashboard resta perfettamente valida, soprattutto se accompagnata da una checklist scritta delle impostazioni applicate. La scelta dell'approccio dipende dalle dimensioni del progetto e dal grado di automazione desiderato. L'importante è essere consistenti e mantenere tracciabilità delle modifiche effettuate.

Hai bisogno di aiuto?

Se vuoi configurare Cloudflare per il tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.