Cloudflare
Provides integration with CloudFlare CDN using the CloudFlare API for cache clearing and client IP restoration.
cloudflare
Overview
The CloudFlare module provides comprehensive integration with the CloudFlare CDN service using the CloudFlare API. It enables Drupal sites to communicate with CloudFlare for cache management and proper client identification.
Key capabilities include cache clearing by Path (recommended for Free and Professional tiers) and by Tag (Enterprise tier only), as well as restoration of the original client IP address that gets masked when CloudFlare operates as a reverse proxy. The module uses a wizard-based configuration approach for easy setup of API credentials and zone selection.
The module includes the CloudFlare Purger submodule which integrates with Drupal's Purge module to provide automated cache invalidation through CloudFlare's API. It supports tag-based, URL-based, and full cache purging, with built-in rate limiting protection and diagnostic checks.
Features
- Cache clearing by URL path (Free and Professional tiers)
- Cache clearing by cache tags (Enterprise tier only)
- Automatic restoration of original client IP address from CloudFlare's CF-Connecting-IP header
- Validation of incoming requests against CloudFlare's IP ranges for security
- Support for both API Key/Email and API Token authentication methods
- Multi-zone support for accounts with multiple CloudFlare zones
- Zone filtering by name for easier selection
- Bypass host configuration to suppress warnings for authenticated user domains
- HTTP middleware for request processing at the earliest stage
- Cache tag header generation in CloudFlare-compatible format with hash-based compression
- Integration with Drupal's Purge module for automated cache invalidation
- Diagnostic checks for API credentials, rate limits, and daily tag purge limits
- Cache tag exclude-list to prevent specific tags from being included in headers
Use Cases
CDN Cache Management for Content Updates
When editors publish or update content in Drupal, the Purge module automatically queues cache invalidations. The CloudFlare Purger processes these queued items and sends purge requests to CloudFlare's API, ensuring that visitors see fresh content without manual cache clearing.
Restoring Visitor IP Addresses
When CloudFlare proxies requests, the server sees CloudFlare's IP instead of the visitor's actual IP. Enable 'Restore Client Ip Address' to have the module automatically restore the original visitor IP from CloudFlare's CF-Connecting-IP header. This is essential for accurate analytics, access logging, and geographic-based functionality.
Enterprise Cache Tag Purging
For CloudFlare Enterprise customers, enable tag-based cache purging for surgical cache invalidation. When a specific node is updated, only pages containing that node's cache tags are purged, rather than clearing the entire CDN cache. The module automatically hashes cache tags to fit CloudFlare's header size limits.
Multi-Site or Multi-Domain Setup
For CloudFlare accounts with multiple zones, use the zone name filter to limit the displayed zones, then select one or more zones to manage. The module will send purge requests to all selected zones.
Separate Editorial Domain
For Free tier users who cannot use CloudFlare's vary-by-cookie feature, configure a separate editorial domain (e.g., edit.example.com) that bypasses CloudFlare. Set this as the 'Host to Bypass CloudFlare' to suppress warning messages when editors access the site directly.
Tips
- For Free tier CloudFlare accounts, cache tags won't work - use URL-based purging via the purge_queuer_url module instead
- Set page cache max age to a high value (31536000 seconds = 1 year) since CloudFlare handles cache invalidation
- The module caches CloudFlare IP ranges permanently; clear cache if CloudFlare updates their IP ranges
- Use the Purge UI at /admin/config/development/performance/purge to monitor purge status and diagnostic checks
- Cache tags are hashed to 4-character strings to fit CloudFlare's header limits; this may cause occasional over-invalidation due to hash collisions
- For high-traffic events, consider the potential for cache tag hash collisions that could cause unintended page purges
- API Tokens are recommended over API Keys as they can be scoped with specific permissions
Technical Details
Admin Pages 3
/admin/config/services/cloudflare
Main configuration page for CloudFlare integration. Uses a two-step wizard approach: first configure API credentials, then select the CloudFlare zone(s).
/admin/config/services/cloudflare/{step}
Second step of the configuration wizard where users select one or more CloudFlare zones from their account.
/admin/config/services/cloudflare/purger
Configure cache tag exclude-list for the CloudFlare Purger.
Permissions 1
Hooks 1
hook_help
Implements hook_help() to provide help text on the module's help page.
Troubleshooting 8
Enable 'Restore Client Ip Address' in the CloudFlare settings. Ensure requests are actually coming through CloudFlare by checking for the CF-Connecting-IP header.
This warning appears when the module expects CloudFlare but requests arrive directly. Either configure a bypass host for editorial domains, or verify your DNS configuration routes traffic through CloudFlare.
This indicates a request has the CF-Connecting-IP header but the connecting IP isn't from CloudFlare. This could be a security issue (spoofed headers) or a legitimate setup like Kubernetes ingress. If legitimate, disable 'Validate remote IP address' (with caution).
Cache tag purging is only available on CloudFlare Enterprise plans. Use URL-based purging for Free and Professional tier accounts.
CloudFlare limits API calls to 1,200 requests per 5 minutes. Reduce purge frequency by batching content updates, using the purge queue processor with appropriate intervals, or excluding high-frequency cache tags from purging.
CloudFlare Enterprise has a limit of 30,000 tag purges per day. Consider using URL-based purging for less critical content, or implementing a cache tag exclude-list for frequently changing but non-critical tags.
This bug was fixed in recent versions. Update to the latest module version to resolve zone pagination issues.
Verify API credentials have permission to access zones. For API Tokens, ensure the token has 'Zone:Read' permission. Try accessing CloudFlare's console to verify zones exist.
Security Notes 5
- API credentials (key/email or token) are stored in Drupal configuration. Ensure configuration exports are properly secured and not committed to public repositories.
- The 'administer cloudflare' permission is marked as restricted due to access to sensitive API credentials.
- When 'Validate remote IP address' is disabled, the module trusts the CF-Connecting-IP header without verifying the request source. This could allow IP spoofing if requests can bypass CloudFlare.
- The module fetches CloudFlare's IP ranges from https://www.cloudflare.com/ips-v4 and ips-v6. Ensure outbound HTTP access is available.
- Consider using CloudFlare API Tokens instead of API Keys for better security through scope limitation.