Skip to content

[WAF] Update upgrade guides #23662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 16, 2025
+36 −45
Merged

[WAF] Update upgrade guides #23662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c9de6e9
[WAF] Update upgrade guides
pedrosousa Jul 15, 2025
2d72d79
Update intro
pedrosousa Jul 16, 2025
572b926
Adjust sentence (SME review)
pedrosousa Jul 16, 2025
7abb750
Remove word
pedrosousa Jul 16, 2025
9ef1cd0
Fix indentation
pedrosousa Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed src/assets/images/waf/custom-rules/custom-rules-tab.png
View file
Open in desktop
Binary file not shown.
33 changes: 15 additions & 18 deletions src/content/docs/waf/reference/legacy/firewall-rules-upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,14 @@ sidebar:
label: Firewall rules upgrade
---

Cloudflare upgraded existing [firewall rules](/firewall/) into [WAF custom rules](/waf/custom-rules/). With custom rules, you get the same level of protection and a few additional features. Custom rules are available in the Cloudflare dashboard at **Security** > **WAF** > **Custom rules**.
Cloudflare upgraded existing [firewall rules](/firewall/) into [custom rules](/waf/custom-rules/). With custom rules, you get the same level of protection and a few additional features. Custom rules are available in the Cloudflare dashboard in the following location:

:::caution[Deprecation notice]
- Old dashboard: **Security** > **WAF** > **Custom rules**.
- New security dashboard: **Security** > **Security rules**.

**Cloudflare Firewall Rules is now deprecated.** The Firewall Rules API and Filters API, as well as the `cloudflare_firewall_rule` and `cloudflare_filter` Terraform resources, will only be available until 2025-06-15. If you have any automation based on these APIs and resources, you must migrate to the new APIs and resources before 2025-06-15 to avoid any issues.
:::caution[Deprecation notice]

On 2025-06-15, the APIs and resources mentioned above will stop working. Any remaining active firewall rules will be disabled, and the **Firewall rules** tab in the dashboard will be removed.
**Cloudflare Firewall Rules is now deprecated.** The Firewall Rules API and Filters API, as well as the `cloudflare_firewall_rule` and `cloudflare_filter` Terraform resources, are no longer supported since 2025-06-15. If you have any automation based on these APIs and resources, you must migrate to the new APIs and resources to avoid any issues.

If you have not upgraded to WAF custom rules yet, you may have some invalid configuration that prevents the upgrade from happening. In this case, contact your account team to get help with the upgrade to WAF custom rules.

Expand All @@ -38,8 +39,7 @@ The default block response is a Cloudflare standard HTML page. If you need to se
To define a custom response for a single rule, go to **Security** > **WAF** > [**Custom rules**](https://dash.cloudflare.com/?to=/:account/:zone/security/waf/custom-rules), edit the custom rule, and fill in the block-related options.

:::note

Custom block response configurations will not be returned by the Firewall Rules API. You must use the [Rulesets API](/waf/custom-rules/create-api/#example-b) to manage this new feature.
Custom block response configurations are not returned by the Firewall Rules API. You must use the [Rulesets API](/waf/custom-rules/create-api/#example-b) to manage this new feature.
:::

### Different error page for blocked requests
Expand Down Expand Up @@ -104,31 +104,29 @@ For the custom rules converted from your existing firewall rules, Cloudflare wil

### Logs and events

Events logged by custom rules are shown in [Security Events](/waf/analytics/security-events/), available at **Security** > **Events**, with `Custom Rules` as their source.
Events logged by custom rules are shown in [Security Events](/waf/analytics/security-events/) with `Custom Rules` as their source.

You may still find events generated by Firewall Rules in the Security Events page when you select a time frame including the days when the transition to custom rules occurred. Similarly, you may still find events with both _Skip_ and _Allow_ actions in the same view during the transition period.

### New API and Terraform resources

The preferred API for managing WAF custom rules is the [Rulesets API](/waf/custom-rules/create-api/). The Rulesets API is used on all recent Cloudflare security products to provide a uniform user experience when interacting with our API. For more information on migrating to the Rulesets API, refer to [Relevant changes for API users](#relevant-changes-for-api-users).

The Firewall Rules API and Filters API will still work until 2025-06-15. There will be a single list of rules for both firewall rules and WAF custom rules, and this list contains WAF custom rules. Thanks to an internal conversion process, the Firewall Rules API and Filters API will return firewall rules/filters converted from these WAF custom rules.
The Firewall Rules API and Filters API are no longer supported since 2025-06-15. There is now a single list of rules for both firewall rules and WAF custom rules, and this list contains WAF custom rules. Thanks to an internal conversion process, the Firewall Rules API and Filters API return firewall rules/filters converted from these WAF custom rules until the APIs sunset date.

If you are using Terraform, the preferred way of configuring WAF custom rules is using [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources configured with the `http_request_firewall_custom` phase. For more information on updating your Terraform configuration, refer to [Relevant changes for Terraform users](#relevant-changes-for-terraform-users).
If you are using Terraform, you must update your configuration to use [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources with the `http_request_firewall_custom` phase to manage custom rules. For more information on updating your Terraform configuration, refer to [Relevant changes for Terraform users](#relevant-changes-for-terraform-users).

## Relevant changes for dashboard users

**The Firewall Rules tab in the Cloudflare dashboard is now deprecated**. Firewall rules are displayed as WAF custom rules in the Cloudflare dashboard at **Security** > **WAF** > **Custom rules**.
**The Firewall Rules tab in the Cloudflare dashboard is now deprecated**. Firewall rules are displayed as [custom rules](/waf/custom-rules/) in the Cloudflare dashboard.

![The Custom rules tab, available in the Cloudflare dashboard under Security > WAF.](~/assets/images/waf/custom-rules/custom-rules-tab.png)

For users that still have access to both products, the **Firewall rules** tab will only be available until 2025-06-15.
For users that have access to both products, the **Firewall rules** tab is only available in the old dashboard in **Security** > **WAF**.

## Relevant changes for API users

**The [Firewall Rules API](/firewall/api/cf-firewall-rules/) and the associated [Cloudflare Filters API](/firewall/api/cf-filters/) are now deprecated.** These APIs will stop working on 2025-06-15. You must manually update any automation based on the Firewall Rules API or Cloudflare Filters API to the [Rulesets API](/waf/custom-rules/create-api/) before this date to prevent any issues. Rule IDs are different between firewall rules and custom rules, which may affect automated processes dealing with specific rule IDs.
**The [Firewall Rules API](/firewall/api/cf-firewall-rules/) and the associated [Cloudflare Filters API](/firewall/api/cf-filters/) are now deprecated.** These APIs are no longer supported since 2025-06-15. You must manually update any automation based on the Firewall Rules API or Cloudflare Filters API to the [Rulesets API](/waf/custom-rules/create-api/) to prevent any issues. Rule IDs are different between firewall rules and custom rules, which may affect automated processes dealing with specific rule IDs.

For the time being, all three APIs will be available (Firewall Rules API, Filters API, and Rulesets API). Cloudflare will internally convert your [Firewall Rules API](/firewall/api/cf-firewall-rules/) and [Filters API](/firewall/api/cf-filters/) calls into the corresponding [Rulesets API](/waf/custom-rules/create-api/) calls. The converted API calls between the Firewall Rules API/Filters API and the Rulesets API appear in audit logs as generated by Cloudflare and not by the actual user making the requests. There will be a single list of rules for both firewall rules and WAF custom rules.
Before the APIs sunset date, Cloudflare will internally convert your [Firewall Rules API](/firewall/api/cf-firewall-rules/) and [Filters API](/firewall/api/cf-filters/) calls into the corresponding [Rulesets API](/waf/custom-rules/create-api/) calls. The converted API calls between the Firewall Rules API/Filters API and the Rulesets API appear in audit logs as generated by Cloudflare and not by the actual user making the requests. There will be a single list of rules for both firewall rules and WAF custom rules.

Some new features of WAF custom rules, like custom responses for blocked requests and the _Skip_ action, are not supported in the Firewall Rules API. To take advantage of these features, Cloudflare recommends that you use the custom rules page in the Cloudflare dashboard or the Rulesets API.

Expand All @@ -141,9 +139,9 @@ Refer to the WAF documentation for [examples of managing WAF custom rules using
- [`cloudflare_firewall_rule`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/firewall_rule)
- [`cloudflare_filter`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/filter)

These resources will stop working on 2025-06-15. If you are currently using these resources to manage your Firewall Rules configuration, you must manually update any Terraform configuration to [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources before this date to prevent any issues.
These resources are no longer supported since 2025-06-15. If you are using these resources to manage your Firewall Rules configuration, you must manually update any Terraform configuration to [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources to prevent any issues.

For the time being, all three Terraform resources will be available (`cloudflare_firewall_rule`, `cloudflare_filter`, and `cloudflare_ruleset`). There will be a single list of rules for both firewall rules and WAF custom rules.
There will be a single list of rules for both firewall rules and WAF custom rules.

Some new features of WAF custom rules are not supported in the deprecated Terraform resources. To take advantage of these features, Cloudflare recommends that you use the `cloudflare_ruleset` resource.

Expand Down Expand Up @@ -215,7 +213,6 @@ The recommended steps for replacing your firewall rules (and filters) configurat
:::caution
You must remove firewall rules and filters from Terraform state before deleting their configuration from `.tf` configuration files to prevent issues.
:::

1. Run the following command to find all resources related to firewall rules and filters:

```sh
Expand Down
14 changes: 6 additions & 8 deletions src/content/docs/waf/reference/legacy/old-rate-limiting/upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The Cloudflare dashboard will now show all your rate limiting rules in a single

**The [Rate Limiting API](/api/resources/rate_limits/) and the [`cloudflare_rate_limit`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/rate_limit) Terraform resource for the previous version of rate limiting rules are now deprecated.**

This API and Terraform resource will only be available until 2025-06-15. After this date you will need to use the [Rulesets API](/ruleset-engine/rulesets-api/) and the [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) Terraform resource to configure rate limiting rules.
This API and Terraform resource are no longer supported since 2025-06-15. You must use the [Rulesets API](/ruleset-engine/rulesets-api/) and the [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) Terraform resource to configure rate limiting rules.

:::

Expand Down Expand Up @@ -60,18 +60,17 @@ For more details on the differences between old and new rate limiting rules, ref
### Relevant changes in the dashboard

If you had access to the previous version of Cloudflare Rate Limiting, you will now find all rate limiting rules in the same list in **Security** > **WAF** > **Rate limiting rules**.

If you are using the new [application security dashboard](/security/) (currently in beta), all the rate limiting rules for your zone will be available at **Security** > **Security rules**.

Rate limiting rules created in the previous version will be tagged with `Previous version` in the Cloudflare dashboard.
Rate limiting rules created in the previous version are tagged with `Previous version` in the Cloudflare dashboard.

![Rate limiting rules user interface showing two rules created in the previous version.](~/assets/images/waf/reference/rate-limiting-rules-upgrade-ui.png)

If you are using the new [application security dashboard](/security/) (currently in beta), only the rate limiting rules that have been upgraded to the new version will be shown at **Security** > **Security rules**.

If you edit a rule with this tag in the dashboard, you will no longer be able to edit the rule using the API and Terraform resource for the previous version of rate limiting rules. In this case, you will need to start using the [Rulesets API](/ruleset-engine/rulesets-api/) or the [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) Terraform resource for this purpose. Refer to [Relevant changes for API users](#relevant-changes-for-api-users) and [Relevant changes for Terraform users](#relevant-changes-for-terraform-users) for more information.

### Relevant changes for API users

**The previous Rate Limiting API is deprecated.** You will not be able to invoke any operations of this API after 2025-06-15. You must update any automation based on the [previous Rate Limiting API](/api/resources/rate_limits/) to the [Rulesets API](/waf/rate-limiting-rules/create-api/) before this date to prevent any issues.
**The previous Rate Limiting API is deprecated.** The API is no longer supported since 2025-06-15. You must update any automation based on the [previous Rate Limiting API](/api/resources/rate_limits/) to the [Rulesets API](/waf/rate-limiting-rules/create-api/) to prevent any issues.

The new rate limiting rules are based on the [Ruleset Engine](/ruleset-engine/). To configure these rate limiting rules via the API you must use the [Rulesets API](/ruleset-engine/rulesets-api/). Since rate limiting rules created in the previous version were upgraded to the new version, this API will also return these rules created in the new version.

Expand All @@ -81,7 +80,7 @@ Until the API sunset date, you can use the [previous Rate Limiting API](/api/res

### Relevant changes for Terraform users

**The `cloudflare_rate_limit` Terraform resource is deprecated.** You will not be able to perform configuration updates via Terraform using this resource after 2025-06-15. You must manually update your rate limiting configuration in Terraform from [`cloudflare_rate_limit`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/rate_limit) resources to [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources before the sunset date to prevent any issues.
**The `cloudflare_rate_limit` Terraform resource is deprecated.** The resource is no longer supported since 2025-06-15. You must manually update your rate limiting configuration in Terraform from [`cloudflare_rate_limit`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/rate_limit) resources to [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources to prevent any issues.

The new rate limiting rules are based on the [Ruleset Engine](/ruleset-engine/). To configure these rate limiting rules with Terraform you must use the `cloudflare_ruleset` Terraform resource.

Expand Down Expand Up @@ -155,7 +154,6 @@ The recommended steps for replacing your old rate limiting configuration in Terr
:::caution[Important]
You must remove rate limiting rules configured through the `cloudflare_rate_limit` resource from Terraform state before deleting their configuration from `.tf` configuration files to prevent issues.
:::

1. Run the following command to find all resources related to rate limiting rules (previous version):

```sh
Expand Down
Loading
Loading