add doc on handling categories, porecedence and app types in gateway via terraform

Author: Rex Scaria

src/content/docs/cloudflare-one/policies/gateway/application-app-types.mdx

@@ -76,3 +76,37 @@ To turn on the Microsoft 365 integration:
 3. To verify the policy was created, select **View policy**. Alternatively, go to **Gateway** > **Firewall policies** > **HTTP**. A policy named Microsoft 365 Auto Generated will be enabled in your list.
 
 All future Microsoft 365 traffic will bypass Gateway logging and filtering. To disable this behavior, turn off or delete the policy.
+
+### How to use app types in terraform?
+
+For terraform users, we offer app types list as a dataset, so that you don't have to mention them by integer id, and instead you can mention them in your policy by the app name.
+
+Example terraform app types setup
+
+<pre> 
+```
+data "cloudflare_zero_trust_gateway_app_types_list" "gateway_apptypes" {
+  account_id     = "<accounbt-id-string>"
+}
+
+
+locals  {
+  apptypes_map = merge([
+    for c in data.cloudflare_zero_trust_gateway_app_types_list.gateway_apptypes.result : {(c.name) = c.id}]...)
+}
+
+resource "cloudflare_zero_trust_gateway_policy" "zt_block_dns_apps" {
+    account_id     = "<accounbt-id-string>"
+    name           = "DNS Blocked apps"
+    action         = "block"
+    traffic        = "any(app.ids[*] in {${join(" ", [
+            local.apptypes_map["Discord"], 
+            local.apptypes_map["GoToMeeting"], 
+            local.apptypes_map["Greenhouse"], 
+            local.apptypes_map["Zelle"], 
+            local.apptypes_map["Microsoft Visual Studio"]
+            ])}})"
+}
+
+```
+</pre>

src/content/docs/cloudflare-one/policies/gateway/domain-categories.mdx

@@ -229,3 +229,44 @@ Then, the initial categorization is refined via:
 3. Machine learning models. Our algorithms, including DGA Domains, DNS tunneling, and phishing detection models analyze patterns and behaviors to detect new and evolving threats.
 
 4. Community feedback. Through a review process, Cloudflare assesses feedback by both our internal models and threat analysts. This ensures that our categorizations reflect the most current and accurate threat intelligence.
+
+## How to use categories in terraform?
+
+For terraform users, we offer categories as a dataset, so that you don't have to mention them by integer id, and instead you can mention them in your policy by the category name.
+
+Example terraform category setup
+
+<pre> 
+```
+data "cloudflare_zero_trust_gateway_categories_list" "categories" {
+  account_id     = "<accounbt-id-string>"
+}
+
+
+locals {
+  main_categories_map = {
+    for idx, c in data.cloudflare_zero_trust_gateway_categories_list.categories[0].result: 
+        c.name => c.id
+  }
+
+  subcategories_map = merge(flatten([
+    for idx, c in data.cloudflare_zero_trust_gateway_categories_list.categories[0].result: {
+        for k,v in coalesce(c.subcategories, []): v.name => v.id
+    }])...)
+}
+
+resource "cloudflare_zero_trust_gateway_policy" "zt_block_dns_tech_categories" {
+    account_id     = "<accounbt-id-string>"
+    name           = "DNS Blocked"
+    action         = "block"
+    traffic        = "any(dns.content_category[*] in {${join(" ", [
+           local.main_categories_map["Technology"], 
+           local.subcategories_map["APIs"], 
+           local.subcategories_map["Artificial Intelligence"], 
+           local.subcategories_map["Content Servers"], 
+           local.subcategories_map["Translator"]
+           ])}})"
+}
+
+```
+</pre>

src/content/partials/cloudflare-one/gateway/order-of-enforcement.mdx

@@ -180,3 +180,51 @@ When a user goes to `https://test.example.com`, Gateway performs the following o
    3. Policy #3 is not evaluated because there has already been an explicit match.
 
 Therefore, the user is able to connect to `https://test.example.com`.
+
+### How gateway calculates precedence?
+
+The gateway API starts assigning precedence to policies created in an account, starting with 1000, unless explictly soecified in the policy otherwise.
+Every time a new policy is added to the bottom of the order, we simply calculate the highest precedence in the account at the moment and
+add 1000 + rand(1...100) to the new policy, so that it now claims the maximum precedence in the account.
+
+Gateway also provides a PUT endpoint to update the precedence of a policy, where the user can set any value for precedence that is not already claimed by another policy. This helps to position a policy in between two already existing policies.
+When polcies are re arranged using dahsboard drag and drop UI, we calculate an appropriate precedence number and assigns it to the policy.
+Changing the order both at UI/API and at terraform might result in stale precedence issues.
+
+### Precedenc management via terraform
+
+Now let's see how we can manage a large number of gateway policies and order of execution via terraform
+
+With terraform v5, gateway users can list thier policies in a terraform file with any integer precedence value as they wish. We suggest starting with 1000 and leave enoughg of a gap inbetween the adjacent policy precedences, so we could sandwitch policies in between those precedence gap in the future.
+
+<pre>
+```
+
+resource "cloudflare_zero_trust_gateway_policy" "policy_1" {
+    account_id     = "<account-id>"
+    .....
+    precedence     = 1000
+}
+
+resource "cloudflare_zero_trust_gateway_policy" "policy_2" {
+    account_id     = "<account-id>"
+    .....
+    precedence     = 2000
+}
+
+
+resource "cloudflare_zero_trust_gateway_policy" "policy_3" {
+    account_id     = "<account-id>"
+    .....
+    precedence     = 3000
+}
+
+
+```
+</pre>
+
+As shown above, way we can arrange the polcies in ascending order of precedence. To move policy 3, to in between policy 1 and policy 2, simply update the precedence of policy 3 to anumber in between [1001..1999], and also move the terraform definition to in between policy 1 and policy 2.
+Mandating a sufficient gap between precedences will make re ordering of policies smoother in the future.
+The only thing to be careful about here is, we recomment moving one policy at a time and applying the state changes. This will cause a complicated reordering manuever to be performed as series of single moves and plan-apply cycles.
+
+Note: If the customer uses a mix of terraform and UI/API, please sync your polices with plan refresh before you start reordering policies in the terraform. You may also lock down your account as terraform only, from the zero trust dashboard settings.

src/content/partials/cloudflare-one/gateway/terraform-precedence-warning.mdx

@@ -2,6 +2,7 @@
 {}
 ---
 
-:::caution[Terraform precedence limitation]
-To avoid conflicts, Terraform applies a hash calculation to policy precedence. For example, a precedence of `1000` may become `1000901`. This can cause errors when reordering policies. To avoid this issue, manually set the precedence of policies created with Terraform using the [Update a Zero Trust Gateway rule](/api/resources/zero_trust/subresources/gateway/subresources/rules/methods/update/) endpoint.
+:::caution[Terraform precedence limitation in v4]
+To avoid conflicts, Terraform applies a hash calculation to policy precedence in v4. For example, a precedence of `1000` may become `1000901`. This can cause errors when reordering policies. To avoid this issue, manually set the precedence of policies created with Terraform using the [Update a Zero Trust Gateway rule](/api/resources/zero_trust/subresources/gateway/subresources/rules/methods/update/) endpoint.
+We suggest you to move to terrafoprm v5, for hazle free handling of precedence. In v5, terraform maintains the exact precedence marked at the policy terraform file.
 :::