Merge pull request #1726 from cloudflare/filter-and-firewall-to-autogen

docs: swap `filter` and `firewall_rule` to automatically generated docs

docs/resources/filter.md

@@ -1,48 +1,44 @@
 ---
-layout: "cloudflare"
-page_title: "Cloudflare: cloudflare_filter"
-description: Provides a Cloudflare Filter expression that can be referenced across multiple features.
+page_title: "cloudflare_filter Resource - Cloudflare"
+subcategory: ""
+description: |-
+  Filter expressions that can be referenced across multiple features, e.g. Firewall Rules. See what is a filter https://developers.cloudflare.com/firewall/api/cf-filters/what-is-a-filter/ for more details and available fields and operators.
 ---
 
-# cloudflare_filter
+# cloudflare_filter (Resource)
 
-Filter expressions that can be referenced across multiple features, e.g. [Firewall Rule](firewall_rule.html). The expression format is similar to [Wireshark Display Filter](https://www.wireshark.org/docs/man-pages/wireshark-filter.html).
+Filter expressions that can be referenced across multiple features, e.g. Firewall Rules. See [what is a filter](https://developers.cloudflare.com/firewall/api/cf-filters/what-is-a-filter/) for more details and available fields and operators.
 
 ## Example Usage
 
-```hcl
+```terraform
 resource "cloudflare_filter" "wordpress" {
-  zone_id = "d41d8cd98f00b204e9800998ecf8427e"
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
   description = "Wordpress break-in attempts that are outside of the office"
-  expression = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
+  expression  = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
 }
 ```
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-## Argument Reference
+### Required
 
-The following arguments are supported:
+- `expression` (String) The filter expression to be used.
+- `zone_id` (String) The zone identifier to target for the resource.
 
-- `zone_id` - (Required) The DNS zone to which the Filter should be added.
-- `paused` - (Optional) Whether this filter is currently paused. Boolean value.
-- `expression` - (Required) The filter expression to be used.
-- `description` - (Optional) A note that you can use to describe the purpose of the filter.
-- `ref` - (Optional) Short reference tag to quickly select related rules.
+### Optional
 
-## Attributes Reference
+- `description` (String) A note that you can use to describe the purpose of the filter.
+- `paused` (Boolean) Whether this filter is currently paused.
+- `ref` (String) Short reference tag to quickly select related rules.
 
-The following attributes are exported:
+### Read-Only
 
-- `id` - Filter identifier.
+- `id` (String) The ID of this resource.
 
 ## Import
 
-Filter can be imported using a composite ID formed of zone ID and filter ID, e.g.
-
-```
-$ terraform import cloudflare_filter.default d41d8cd98f00b204e9800998ecf8427e/9e107d9d372bb6826bd81d3542a419d6
+Import is supported using the following syntax:
+```shell
+$ terraform import cloudflare_filter.example <zone_id>/<filter_id>
 ```
-
-where:
-
-- `d41d8cd98f00b204e9800998ecf8427e` - zone ID
-- `9e107d9d372bb6826bd81d3542a419d6` - filter ID as returned by [API](https://api.cloudflare.com/#zone-firewall-filters)

docs/resources/firewall_rule.md

@@ -1,62 +1,64 @@
 ---
-layout: "cloudflare"
-page_title: "Cloudflare: cloudflare_firewall_rule"
-description: Define Firewall rule using filter expression for more control over how traffic is matched to the rule.
+page_title: "cloudflare_firewall_rule Resource - Cloudflare"
+subcategory: ""
+description: |-
+  Define Firewall rules using filter expressions for more control over how traffic is matched to the rule.
+  A filter expression permits selecting traffic by multiple criteria allowing greater freedom in rule creation.
+  Filter expressions needs to be created first before using Firewall Rule.
 ---
 
-# cloudflare_firewall_rule
+# cloudflare_firewall_rule (Resource)
 
 Define Firewall rules using filter expressions for more control over how traffic is matched to the rule.
 A filter expression permits selecting traffic by multiple criteria allowing greater freedom in rule creation.
 
-Filter expressions needs to be created first before using Firewall Rule. See [Filter](filter.html).
+Filter expressions needs to be created first before using Firewall Rule.
 
-If you want to configure Custom Firewall rules, you need to use [cloudflare_ruleset](ruleset.html), because Custom Rules are built upon the
+~> If you want to configure Custom Firewall rules, you need to use
+`cloudflare_ruleset`, because Custom Rules are built upon the
 [Cloudflare Ruleset Engine](https://developers.cloudflare.com/ruleset-engine/).
 
 ## Example Usage
 
-```hcl
+```terraform
 resource "cloudflare_filter" "wordpress" {
-  zone_id = "d41d8cd98f00b204e9800998ecf8427e"
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
   description = "Wordpress break-in attempts that are outside of the office"
-  expression = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
+  expression  = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
 }
 
 resource "cloudflare_firewall_rule" "wordpress" {
-  zone_id = "d41d8cd98f00b204e9800998ecf8427e"
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
   description = "Block wordpress break-in attempts"
-  filter_id = cloudflare_filter.wordpress.id
-  action = "block"
+  filter_id   = cloudflare_filter.wordpress.id
+  action      = "block"
 }
 ```
 
-## Argument Reference
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-The following arguments are supported:
+### Required
 
-- `zone_id` - (Required) The DNS zone to which the Filter should be added.
-- `action` - (Required) The action to apply to a matched request. Allowed values: "block", "challenge", "allow", "js_challenge", "managed_challenge", "bypass". Enterprise plan also allows "log".
-- `priority` - (Optional) The priority of the rule to allow control of processing order. A lower number indicates high priority. If not provided, any rules with a priority will be sequenced before those without.
-- `paused` - (Optional) Whether this filter based firewall rule is currently paused. Boolean value.
-- `description` - (Optional) A description of the rule to help identify it.
-- `products` - (Optional) List of products to bypass for a request when the bypass action is used. Allowed values: "zoneLockdown", "uaBlock", "bic", "hot", "securityLevel", "rateLimit", "waf".
+- `action` (String) The action to apply to a matched request. Available values: `block`, `challenge`, `allow`, `js_challenge`, `managed_challenge`, `log`, `bypass`.
+- `filter_id` (String) The identifier of the Filter to use for determining if the Firewall Rule should be triggered.
+- `zone_id` (String) The zone identifier to target for the resource.
 
-## Attributes Reference
+### Optional
 
-The following attributes are exported:
+- `description` (String) A description of the rule to help identify it.
+- `paused` (Boolean) Whether this filter based firewall rule is currently paused.
+- `priority` (Number) The priority of the rule to allow control of processing order. A lower number indicates high priority. If not provided, any rules with a priority will be sequenced before those without.
+- `products` (Set of String) List of products to bypass for a request when the bypass action is used. Available values: `zoneLockdown`, `uaBlock`, `bic`, `hot`, `securityLevel`, `rateLimit`, `waf`.
 
-- `id` - Firewall Rule identifier.
+### Read-Only
+
+- `id` (String) The ID of this resource.
 
 ## Import
 
-Firewall Rule can be imported using a composite ID formed of zone ID and rule ID, e.g.
+Import is supported using the following syntax:
 
+```shell
+$ terraform import cloudflare_firewall_rule.example <zone_id>/<firewall_rule_id>
 ```
-$ terraform import cloudflare_firewall_rule.default d41d8cd98f00b204e9800998ecf8427e/9e107d9d372bb6826bd81d3542a419d6
-```
-
-where:
-
-- `d41d8cd98f00b204e9800998ecf8427e` - zone ID
-- `9e107d9d372bb6826bd81d3542a419d6` - rule ID as returned by [API](https://api.cloudflare.com/#zone-firewall-filter-rules)

examples/resources/cloudflare_filter/import.sh

@@ -0,0 +1 @@
+$ terraform import cloudflare_filter.example <zone_id>/<filter_id>

examples/resources/cloudflare_filter/resource.tf

@@ -0,0 +1,5 @@
+resource "cloudflare_filter" "wordpress" {
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
+  description = "Wordpress break-in attempts that are outside of the office"
+  expression  = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
+}

examples/resources/cloudflare_firewall_rule/import.sh

@@ -0,0 +1 @@
+$ terraform import cloudflare_firewall_rule.example <zone_id>/<firewall_rule_id>

examples/resources/cloudflare_firewall_rule/resource.tf

@@ -0,0 +1,12 @@
+resource "cloudflare_filter" "wordpress" {
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
+  description = "Wordpress break-in attempts that are outside of the office"
+  expression  = "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.src ne 192.0.2.1"
+}
+
+resource "cloudflare_firewall_rule" "wordpress" {
+  zone_id     = "d41d8cd98f00b204e9800998ecf8427e"
+  description = "Block wordpress break-in attempts"
+  filter_id   = cloudflare_filter.wordpress.id
+  action      = "block"
+}

internal/provider/resource_cloudflare_filter.go

@@ -21,6 +21,7 @@ func resourceCloudflareFilter() *schema.Resource {
 		Importer: &schema.ResourceImporter{
 			StateContext: resourceCloudflareFilterImport,
 		},
+		Description: "Filter expressions that can be referenced across multiple features, e.g. Firewall Rules. See [what is a filter](https://developers.cloudflare.com/firewall/api/cf-filters/what-is-a-filter/) for more details and available fields and operators.",
 	}
 }
 

internal/provider/resource_cloudflare_firewall_rule.go

@@ -21,6 +21,12 @@ func resourceCloudflareFirewallRule() *schema.Resource {
 		Importer: &schema.ResourceImporter{
 			StateContext: resourceCloudflareFirewallRuleImport,
 		},
+		Description: `
+Define Firewall rules using filter expressions for more control over how traffic is matched to the rule.
+A filter expression permits selecting traffic by multiple criteria allowing greater freedom in rule creation.
+
+Filter expressions needs to be created first before using Firewall Rule.
+		`,
 	}
 }
 

internal/provider/schema_cloudflare_filter.go

@@ -17,15 +17,17 @@ func resourceCloudflareFilterSchema() map[string]*schema.Schema {
 			ForceNew:    true,
 		},
 		"paused": {
-			Type:     schema.TypeBool,
-			Optional: true,
+			Type:        schema.TypeBool,
+			Optional:    true,
+			Description: "Whether this filter is currently paused.",
 		},
 		"expression": {
 			Type:     schema.TypeString,
 			Required: true,
 			DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool {
 				return strings.TrimSpace(new) == old
 			},
+			Description: "The filter expression to be used.",
 		},
 		"description": {
 			Type:         schema.TypeString,
@@ -37,11 +39,13 @@ func resourceCloudflareFilterSchema() map[string]*schema.Schema {
 				}
 				return false
 			},
+			Description: "A note that you can use to describe the purpose of the filter.",
 		},
 		"ref": {
 			Type:         schema.TypeString,
 			Optional:     true,
 			ValidateFunc: validation.StringLenBetween(0, 50),
+			Description:  "Short reference tag to quickly select related rules.",
 		},
 	}
 }

internal/provider/schema_cloudflare_firewall_rule.go

@@ -1,6 +1,7 @@
 package provider
 
 import (
+	"fmt"
 	"html"
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -16,18 +17,21 @@ func resourceCloudflareFirewallRuleSchema() map[string]*schema.Schema {
 			ForceNew:    true,
 		},
 		"filter_id": {
-			Type:     schema.TypeString,
-			Required: true,
+			Type:        schema.TypeString,
+			Required:    true,
+			Description: "The identifier of the Filter to use for determining if the Firewall Rule should be triggered.",
 		},
 		"action": {
 			Type:         schema.TypeString,
 			Required:     true,
 			ValidateFunc: validation.StringInSlice([]string{"block", "challenge", "allow", "js_challenge", "managed_challenge", "log", "bypass"}, false),
+			Description:  fmt.Sprintf("The action to apply to a matched request. %s", renderAvailableDocumentationValuesStringSlice([]string{"block", "challenge", "allow", "js_challenge", "managed_challenge", "log", "bypass"})),
 		},
 		"priority": {
 			Type:         schema.TypeInt,
 			Optional:     true,
 			ValidateFunc: validation.IntBetween(1, 2147483647),
+			Description:  "The priority of the rule to allow control of processing order. A lower number indicates high priority. If not provided, any rules with a priority will be sequenced before those without.",
 		},
 		"description": {
 			Type:         schema.TypeString,
@@ -39,18 +43,21 @@ func resourceCloudflareFirewallRuleSchema() map[string]*schema.Schema {
 				}
 				return false
 			},
+			Description: "A description of the rule to help identify it.",
 		},
 		"paused": {
-			Type:     schema.TypeBool,
-			Optional: true,
+			Type:        schema.TypeBool,
+			Optional:    true,
+			Description: "Whether this filter based firewall rule is currently paused.",
 		},
 		"products": {
 			Type: schema.TypeSet,
 			Elem: &schema.Schema{
 				Type:         schema.TypeString,
 				ValidateFunc: validation.StringInSlice([]string{"zoneLockdown", "uaBlock", "bic", "hot", "securityLevel", "rateLimit", "waf"}, false),
 			},
-			Optional: true,
+			Optional:    true,
+			Description: fmt.Sprintf("List of products to bypass for a request when the bypass action is used. %s", renderAvailableDocumentationValuesStringSlice([]string{"zoneLockdown", "uaBlock", "bic", "hot", "securityLevel", "rateLimit", "waf"})),
 		},
 	}
 }