https://github.com/faserf/ha-cloudflare
Homeassistant Integration to interact with Cloudflare Cloud
https://github.com/faserf/ha-cloudflare
cloudflare custom-integration hacs homeassistant integration
Last synced: about 1 month ago
JSON representation
Homeassistant Integration to interact with Cloudflare Cloud
- Host: GitHub
- URL: https://github.com/faserf/ha-cloudflare
- Owner: FaserF
- License: mit
- Created: 2026-04-28T13:42:43.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T05:59:24.000Z (about 2 months ago)
- Last Synced: 2026-05-12T07:37:28.606Z (about 2 months ago)
- Topics: cloudflare, custom-integration, hacs, homeassistant, integration
- Language: Python
- Homepage:
- Size: 173 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cloudflare Advanced (for Home Assistant)
[](https://github.com/FaserF/ha-cloudflare/releases)
[](LICENSE)
[](https://hacs.xyz)
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=cloudflare_advanced)
[](https://github.com/FaserF/ha-cloudflare/actions/workflows/ci-orchestrator.yml)
A secure, production-ready Home Assistant integration for Cloudflare. Monitor zone analytics, manage Zero Trust tunnels, control page rules, secure apps, and modify DNS records directly from Home Assistant.
## 🧭 Quick Links
| | | | |
| :--- | :--- | :--- | :--- |
| [✨ Features](#-features) | [📦 Installation](#-installation) | [⚙️ Configuration](#️-configuration) | [🛡️ Security](#-security) |
| [🧱 Services](#-services) | [📖 Automations](#-automation-examples) | [❓ FAQ](#-troubleshooting--faq) | [🧑💻 Development](#-development) |
| [💖 Credits](#-credits--acknowledgements) | [📄 License](#-license) | | |
### Why use this integration?
While generic DNS updates only provide simple IP changes, this integration leverages Cloudflare APIs (REST & GraphQL) to offer deep administrative control. Manage multiple zones, workers, turnstile widgets, access policies, and Zero Trust tunnels in one cohesive dashboard without accessing complex terminals.
## ✨ Features
- **Zone Analytics**:
- **Requests**: Real-time traffic insights.
- **Bandwidth**: Data transfer metrics (in Megabytes).
- **Threats Blocked**: See how many malicious requests were prevented.
- **Unique Visitors**: Track visitor metrics.
- **Certificate Expiration**: Monitor edge certificate expiry dates.
- **Zero Trust & Tunnels**:
- **Tunnel Status**: Monitor status (Connected/Healthy) for Cloudflare Tunnels.
- **Details**: Track active connection counts and connector daemon versions.
- **Gateway Policies**: Toggle Zero Trust DNS/HTTP policies on or off.
- **Load Balancer Pools**: View health diagnostics for origin server distributions.
- **Registrar Domains**: Track the expiration date of domains registered via Cloudflare.
- **Access Applications, Edge Workers & Pages**:
- **Access Apps**: Monitor active statuses for protected assets.
- **Workers Deployment**: Get uptime diagnostics for deployed Cloudflare Workers.
- **Pages Deployment**: Track the live deployment state of Cloudflare Pages.
- **Turnstile Widgets**: Monitor mode configurations.
- **Cloudflare Images**: Monitor stored vs allowed capacities.
- **Configurable Control**:
- **Zone Settings**: Toggles for Development Mode, Always Use HTTPS, Automatic HTTPS Rewrites, IPv6 Compatibility, Rocket Loader, WebSockets, Brotli, Hotlink Protection, and Early Hints.
- **Security Level**: Dropdown options to force immediate strictness (`off`, `essentially_off`, `low`, `medium`, `high`, `under_attack`).
- **Page Rules**: Disable or enable individual URL filters.
- **Email Routing**: Toggle custom email forwarding rules on or off.
- **WAF Rules**: Toggle specific WAF Custom rules to secure origins.
- **Cache Rules**: Toggle specific advanced caching behavior rules.
- **Domain Auto-Renew**: Toggle domain registration auto-renewals safely.
- **API Quota Monitoring**: Tracks remaining API requests and reset time to prevent rate limiting.
- **Security Logs**: Tracks external attack properties (`Country`, `IP Address`, `Rule Triggered`).
- **Smart Tracking & Logic**:
- **Automated DDNS Updates**: Automatically detects your router's public IP changes using `Home Assistant` networking infrastructure, seamlessly propagating changes onto mapped Zone A-Records (Configurable via Options Flow).
- **Cache Management**: Instantly purge your Cloudflare Zone Cache using custom hardware buttons.
## ❤️ Support This Project
> I maintain this integration in my **free time alongside my regular job** — bug hunting, new features, testing. Test environments cost money, and every donation helps me stay independent and dedicate more time to open-source work.
>
> **This project is and will always remain 100% free.** There are no "Premium Upgrades" or subscriptions.
>
> Donations are completely voluntary — but the more support I receive, the less I depend on other income sources. 💪
[](https://github.com/sponsors/FaserF)
[](https://paypal.me/FaserF)
## 📦 Installation
### HACS (Recommended)
This integration is fully compatible with [HACS](https://hacs.xyz/).
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=FaserF&repository=ha-cloudflare&category=Integration)
1. Open HACS in Home Assistant.
2. Click the three dots in the top right corner and select **Custom repositories**.
3. Add `FaserF/ha-cloudflare` with category **Integration**.
4. Search for "Cloudflare Advanced".
5. Install and restart Home Assistant.
### Manual Installation
1. Download the latest release from the [Releases page](https://github.com/FaserF/ha-cloudflare/releases).
2. Extract the `custom_components/cloudflare_advanced` folder into your Home Assistant's `custom_components` directory.
3. Restart Home Assistant.
## ⚙️ Configuration
Adding your Cloudflare account is entirely done via the UI. **No YAML configuration is required.**
1. Navigate to **Settings > Devices & Services** in Home Assistant.
2. Click **Add Integration** and search for **Cloudflare Advanced**.
3. Choose Authentication:
- **API Token (Recommended)**: Generate a secure scoped token.
- **Legacy Credentials**: E-Mail address + Global API Key.
4. Select which active domain zones you wish to initialize.
## 🛡️ Security
To use the recommended API Token method, you must generate a token in your Cloudflare account.
You can jump directly to the [Cloudflare API Tokens Dashboard](https://dash.cloudflare.com/profile/api-tokens) or follow these steps manually:
1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com/).
2. In the top right, click on your **Profile Icon** and select **My Profile**.
3. Go to the **API Tokens** tab.
4. Click **Create Token** and select **Create Custom Token**.
For a comprehensive step-by-step tutorial, refer to the official [Cloudflare Token Creation Guide](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/).
Ensure your generated API Token follows the **Principle of Least Privilege**. Grant access solely to the required scopes for your selected domains:
### Required Scopes (Zone-level)
- `Analytics` (Read) - For traffic & security metrics.
- `Zone` (Read) - For zone discovery and metadata.
- `Zone Settings` (Read/Edit) - For performance and network toggles.
- `Page Rules` (Read/Edit) - For URL filter management.
- `DNS` (Read/Edit) - For DDNS updates and record control.
- `Firewall Services` (Read/Edit) - For custom WAF rule toggles.
- `Cache Rules` (Read/Edit) - For advanced Cache rules.
- `Email Routing` (Read/Edit) - For email forwarding rule control.
- `Cache Purge` (Edit) - For manual cache clearing.
### Optional Scopes (Account-level)
- `Cloudflare Zero Trust` (Read/Edit) - For Tunnels and Gateway policies.
- `Workers Scripts` (Read) - For Worker status tracking.
- `Cloudflare Pages` (Read) - For project deployment status.
- `Cloudflare Images` (Read) - For storage capacity monitoring.
- `Load Balancing` (Read) - For health diagnostics of LB pools.
- `Registrar` (Read/Edit) - For domain management and auto-renew toggles.
## 🧱 Services
The integration provides powerful actions for deployment management.
### `cloudflare_advanced.purge_cache`
Purges files stored on edge cache layers.
- **`zone_id`**: (Required) Unique identifier of the domain zone.
- **`purge_everything`**: (Optional) Clears all cached elements if True (default: `true`).
- **`files`**: (Optional) Specify exact asset URLs to selectively wipe.
### `cloudflare_advanced.update_dns_record`
Updates IP targets.
- **`zone_id`**: (Required) Target Cloudflare Zone.
- **`record_id`**: (Required) Cloudflare record reference.
- **`name`**: (Required) Record name string (e.g. `sub.example.com`).
- **`type`**: (Required) Protocol format (`A`, `CNAME`, `AAAA`).
- **`content`**: (Required) Upstream destination.
### `cloudflare_advanced.create_dns_record`
Constructs completely new entries.
- **`zone_id`**: (Required) Domain reference.
- **`name`**: (Required) Title endpoint string.
- **`type`**: (Required) Schema type.
- **`content`**: (Required) IP binding.
## 📖 Automation Examples
🔄 Auto-Disable Dev Mode After Hours
```yaml
alias: "Cloudflare: Time Dev Mode"
trigger:
- platform: state
entity_id: switch.example_com_development_mode
to: "on"
for:
hours: 4
action:
- target:
entity_id: switch.example_com_development_mode
action: switch.turn_off
```
🛡️ Respond to Threat Spikes
```yaml
alias: "Cloudflare: Under Attack State"
trigger:
- platform: numeric_state
entity_id: sensor.example_com_threats_blocked
above: 25
action:
- target:
entity_id: select.example_com_security_level
action: select.select_option
data:
option: "under_attack"
```
🚨 Push Alerts on VPN Tunnel Failures
```yaml
alias: "Cloudflare: Tunnel Status Notification"
trigger:
- platform: state
entity_id: binary_sensor.tunnel_main_gateway
to: "off"
action:
- action: notify.notify
data:
title: "Tunnel Error"
message: "Gateway link dropped."
```
## ❓ Troubleshooting & FAQ
### "Invalid Auth" during setup
Check token permissions. Tokens restricted from accessing general lists fail verification. Verify Zone read privileges.
### Why are some controls missing?
Specific operations rely upon the Tier setup in Cloudflare profiles. Free profiles lack some complex variables.
## 🧑💻 Development
Uses:
- `ruff` linting
- `pytest` frameworks
- `mypy` validation
## 💖 Credits & Acknowledgements
Built from the ground up to provide a complete replacement for basic dynamic IP workflows.
## 📄 License
MIT License - see the [LICENSE](LICENSE) file for details.