add doc on handling categories and app types in gateway via terraform (#21983)

Co-authored-by: Rex Scaria <[email protected]>
Co-authored-by: Max Phillips <[email protected]>

Author: 3 people

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

@@ -15,6 +15,8 @@ When you choose the _Application_ selector in a Gateway policy builder, the **Va
 
 ## App types
 
+Gateway sorts applications into the following app type groups:
+
 | Value                                          | Definition                                                                                                                  |
 | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | Artificial Intelligence                        | AI assistance applications                                                                                                  |
@@ -43,20 +45,9 @@ When you choose the _Application_ selector in a Gateway policy builder, the **Va
 | Video Streaming                                | Video streaming applications                                                                                                |
 | [Do Not Inspect](#do-not-inspect-applications) | Applications incompatible with the TLS certificate required by the [Gateway proxy](/cloudflare-one/policies/gateway/proxy/) |
 
-### Do Not Inspect applications
-
-#### TLS decryption limitations
-
-Applications can be incompatible with [TLS decryption](/cloudflare-one/policies/gateway/http-policies/tls-decryption/) for various reasons:
-
-<GlossaryDefinition
-	term="certificate pinning"
-	prepend="Certificate pinning is "
-/>
-
-- **Non-web traffic**: Some applications send non-web traffic, such as Session Initiation Protocol (SIP) and Extensible Messaging and Presence Protocol (XMPP), over TLS. Gateway cannot inspect these protocols.
+## Usage
 
-#### Application grouping
+### Do Not Inspect applications
 
 Gateway automatically groups applications incompatible with TLS decryption into the _Do Not Inspect_ app type. As Cloudflare identifies incompatible applications, Gateway will periodically update this app type to add new applications. To ensure Gateway does not intercept any current or future incompatible traffic, you can [create a Do Not Inspect HTTP policy](/cloudflare-one/policies/gateway/http-policies/#do-not-inspect) with the entire _Do Not Inspect_ app type selected.
 
@@ -65,6 +56,17 @@ Gateway automatically groups applications incompatible with TLS decryption into
 Instead of creating a Do Not Inspect policy for an application, you may be able to configure the application to [trust a Cloudflare certificate](/cloudflare-one/connections/connect-devices/user-side-certificates/manual-deployment/#add-the-certificate-to-applications). Doing so will allow the application to function without losing visibility into your traffic.
 :::
 
+#### TLS decryption limitations
+
+Applications can be incompatible with [TLS decryption](/cloudflare-one/policies/gateway/http-policies/tls-decryption/) for various reasons:
+
+- <GlossaryDefinition
+  	term="certificate pinning"
+  	prepend="**Certificate pinning**: Certificate pinning is "
+  />
+
+- **Non-web traffic**: Some applications send non-web traffic, such as Session Initiation Protocol (SIP) and Extensible Messaging and Presence Protocol (XMPP), over TLS. Gateway cannot inspect these protocols.
+
 #### Microsoft 365 integration
 
 To optimize performance for Microsoft 365 applications and services, you can bypass TLS decryption by turning on the Microsoft 365 traffic integration. This will create a [Do Not Inspect policy](/cloudflare-one/policies/gateway/http-policies/#do-not-inspect) for all [Microsoft 365 domains and IP addresses](https://docs.microsoft.com/en-us/microsoft-365/enterprise/microsoft-365-ip-web-service) specified by Microsoft. This policy also uses Cloudflare intelligence to identify other Microsoft 365 traffic not explicitly defined.
@@ -76,3 +78,33 @@ 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.
+
+### Terraform
+
+Terraform users can retrieve the app types list with the `cloudflare_zero_trust_gateway_app_types_list` data source. This allows you to create Gateway policies with the application's name rather than its numeric UUID. For example:
+
+```tf
+data "cloudflare_zero_trust_gateway_app_types_list" "gateway_apptypes" {
+  account_id = var.cloudflare_account_id
+}
+
+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 = var.cloudflare_account_id
+  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"]
+  ])}})"
+}
+```

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

@@ -229,3 +229,40 @@ 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.
+
+## Terraform
+
+Terraform users can retrieve the category list with the `cloudflare_zero_trust_gateway_categories_list` data source. This allows you to create Gateway policies with the category's name rather than its numeric UUID. For example:
+
+```tf
+data "cloudflare_zero_trust_gateway_categories_list" "categories" {
+  account_id = var.cloudflare_account_id
+}
+
+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 = var.cloudflare_account_id
+  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"]
+  ])}})"
+}
+```

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

@@ -180,3 +180,37 @@ 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`.
+
+## Precedence calculations
+
+When arranging policies in Zero Trust, Gateway automatically calculates the precedence for rearranged policies.
+
+When using the API to create a policy, unless the precedence is explicitly defined in the policy, Gateway will assign precedence to policies starting at `1000`. Every time a new policy is added to the bottom of the order, Gateway will calculate the current highest precedence in the account and add a random integer between 1 and 100 to `1000` so that it now claims the maximum precedence in the account. To manually update a policy's precedence, use the [Update a Zero Trust Gateway rule](/api/resources/zero_trust/subresources/gateway/subresources/rules/methods/update/) endpoint. You can set a policy's precedence to any value that is not already in use.
+
+Changing the order within the Zero Trust dashboard or API may result in configuration issues when using [Terraform](#manage-precedence-with-terraform).
+
+## Manage precedence with Terraform
+
+You can manage a the order of execution of your Gateway policies using Terraform. With version 5 of the Terraform Cloudflare provider, Gateway users can list their policies in a Terraform file with any desired integer precedence value. Cloudflare recommends starting with a precedence of `1000` and adding extra space between each policy's precedence for any future policies. For example:
+
+```tf
+resource "cloudflare_zero_trust_gateway_policy" "policy_1" {
+  account_id = var.cloudflare_account_id
+  # other attributes...
+  precedence = 1000
+}
+
+resource "cloudflare_zero_trust_gateway_policy" "policy_2" {
+  account_id = var.cloudflare_account_id
+  # other attributes...
+  precedence = 2000
+}
+
+resource "cloudflare_zero_trust_gateway_policy" "policy_3" {
+  account_id = var.cloudflare_account_id
+  # other attributes...
+  precedence = 3000
+}
+```
+
+To avoid precedence calculation errors, you should move one policy at a time before running `terraform plan` and `terraform apply`. If you use both Terraform and the Zero Trust dashboard or API, sync your polices with `terraform plan` before reordering policies in Terraform. Alternatively, you can set your account to [read-only in the Zero Trust dashboard](/cloudflare-one/api-terraform/#set-dashboard-to-read-only), only allowing changes using the API or Terraform.

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

@@ -2,6 +2,8 @@
 {}
 ---
 
-:::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 provider v4 precedence limitation]
+To avoid conflicts, version 4 of the Terraform Cloudflare provider 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.
+
+To ensure your precedence is set correctly, Cloudflare recommends [upgrading your Terraform provider to version 5](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/guides/version-5-upgrade).
 :::