[Terraform] Fix rule ID changes (#18630)

Author: pedrosousa

src/content/docs/terraform/additional-configurations/index.mdx

@@ -3,9 +3,10 @@ title: Additional configurations
 pcx_content_type: navigation
 sidebar:
   order: 4
-
+  group:
+    hideIndex: true
 ---
 
-import { DirectoryListing } from "~/components"
+import { DirectoryListing } from "~/components";
 
 <DirectoryListing />

src/content/docs/terraform/advanced-topics/index.mdx

@@ -3,9 +3,10 @@ pcx_content_type: navigation
 title: Advanced topics
 sidebar:
   order: 5
-
+  group:
+    hideIndex: true
 ---
 
-import { DirectoryListing } from "~/components"
+import { DirectoryListing } from "~/components";
 
 <DirectoryListing />

src/content/docs/terraform/troubleshooting/index.mdx

@@ -0,0 +1,14 @@
+---
+pcx_content_type: navigation
+title: Troubleshooting
+sidebar:
+  order: 6
+  group:
+    hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+The following pages are useful for troubleshooting Terraform issues.
+
+<DirectoryListing />

src/content/docs/terraform/troubleshooting/rule-id-changes.mdx

@@ -0,0 +1,26 @@
+---
+pcx_content_type: troubleshooting
+title: The rule ID changes when I modify a rule
+sidebar:
+  label: Rule ID changes
+---
+
+For [`cloudflare_ruleset`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/ruleset) resources, the Cloudflare provider may delete a rule and create a new one when you modify a ruleset rule in your Terraform configuration. This happens when the provider cannot match your new rule configuration in Terraform with an existing rule in your Cloudflare configuration. In this situation, modifying a rule in your Terraform configuration and applying the changes will create a new rule with a different rule ID in your Cloudflare account or zone.
+
+This behavior may have an impact on any automation or monitoring systems you may have configured that rely on having immutable rule IDs between rule modifications.
+
+## How to keep the same rule ID between modifications
+
+To keep the existing rule ID when making changes to a rule through Terraform, add a `ref` field to the rule.
+
+The `ref` field is a user-defined external identifier that must be unique for each rule in a ruleset. When you provide a `ref` value, the provider will match the rule in your updated Terraform configuration with the existing rule with the same `ref` external identifier, and the rule ID will be preserved.
+
+`ref` values have a string data type with a minimum length of one character. For example, `my_ref`.
+
+## `cf-terraforming` support for `ref` field values
+
+By default, when you create a rule, its `ref` value will be equal to the rule ID. You can set or modify `ref` values via Cloudflare API.
+
+When you [import your existing Cloudflare configuration to Terraform](/terraform/advanced-topics/import-cloudflare-resources/) using [`cf-terraforming`](https://github.com/cloudflare/cf-terraforming), the generated Terraform configuration will have `ref` values for each rule, with the same value as the rule ID.
+
+If you manually created your Terraform configuration and your rules' configuration does not have a `ref` field, add a `ref` field to each rule so that each rule modification does not generate a new rule ID.