WAF documentation enhancements (#30)

* WAF documentation enhancements

website/docs/d/waf_rules.html.markdown

@@ -44,7 +44,7 @@ Usage without filters:
 
 ```hcl
 data "fastly_waf_rules" "all" {
-  // This will retrieve the entire list of rules available from the API at the time.
+  # This will retrieve the entire list of rules available from the API at the time.
 }
 ```
 
@@ -137,6 +137,8 @@ resource "fastly_service_waf_configuration_v1" "waf" {
 
 * `rules` - The Web Application Firewall's rules result set.
 
+~> **Warning:** Deprecated rules will not be present on this data source's result set.
+
 The `rules` block supports:
 
 * `modsec_rule_id` - The rule's modsecurity ID.

website/docs/r/service_waf_configuration_v1.html.markdown

@@ -213,7 +213,7 @@ resource "fastly_service_waf_configuration_v1" "waf" {
 Usage with support for individual rule configuration (this is the suggested pattern):
 
 ```hcl
-// this variable is used for rule configuration in bulk
+# this variable is used for rule configuration in bulk
 variable "type_status" {
   type = map(string)
   default = {
@@ -222,7 +222,7 @@ variable "type_status" {
     strict    = "log"
   }
 }
-// this variable is used for individual rule configuration
+# this variable is used for individual rule configuration
 variable "individual_rules" {
   type = map(string)
   default = {
@@ -289,7 +289,7 @@ resource "fastly_service_waf_configuration_v1" "waf" {
     content {
       modsec_rule_id = rule.value.modsec_rule_id
       revision       = rule.value.latest_revision_number
-      // Nested lookups in order to apply a combination of in bulk and individual rule configuration.
+      # Nested lookups in order to apply a combination of in bulk and individual rule configuration.
       status         = lookup(var.individual_rules, rule.value.modsec_rule_id, lookup(var.type_status, rule.value.type, "log"))
     }
   }
@@ -299,7 +299,7 @@ resource "fastly_service_waf_configuration_v1" "waf" {
 Usage with support for specific rule revision configuration:
 
 ```hcl
-// this variable is used for rule configuration in bulk
+# this variable is used for rule configuration in bulk
 variable "type_status" {
   type = map(string)
   default = {
@@ -309,11 +309,11 @@ variable "type_status" {
   }
 }
 
-// This variable is used for individual rule revision configuration.
+# This variable is used for individual rule revision configuration.
 variable "specific_rule_revisions" {
   type = map(string)
   default = {
-    //  If the revision requested is not found, the server will return a 404 response code.
+    #  If the revision requested is not found, the server will return a 404 response code.
     1010020 = 1
   }
 }
@@ -383,6 +383,95 @@ resource "fastly_service_waf_configuration_v1" "waf" {
 }
 ```
 
+Usage omitting rule revision field. The first time Terraform is applied, the latest rule revisions are associated with the WAF. Any subsequent apply would not alter the rule revisions.
+
+```hcl
+# This variable is used for rule configuration in bulk.
+variable "type_status" {
+  type = map(string)
+  default = {
+    score     = "score"
+    threshold = "log"
+    strict    = "log"
+  }
+}
+# This variable is used for individual rule configuration.
+variable "individual_rules" {
+  type = map(string)
+  default = {
+    1010020 = "block"
+  }
+}
+
+resource "fastly_service_v1" "demo" {
+  name = "demofastly"
+
+  domain {
+    name    = "example.com"
+    comment = "demo"
+  }
+
+  backend {
+    address = "127.0.0.1"
+    name    = "origin1"
+    port    = 80
+  }
+
+  condition {
+    name      = "WAF_Prefetch"
+    type      = "PREFETCH"
+    statement = "req.backend.is_origin"
+  }
+
+  # This condition will always be false
+  # adding it to the response object created below
+  # prevents Fastly from returning a 403 on all of your traffic.
+  condition {
+    name      = "WAF_always_false"
+    statement = "false"
+    type      = "REQUEST"
+  }
+
+  response_object {
+    name              = "WAF_Response"
+    status            = "403"
+    response          = "Forbidden"
+    content_type      = "text/html"
+    content           = "<html><body>Forbidden</body></html>"
+    request_condition = "WAF_always_false"
+  }
+
+  waf {
+    prefetch_condition = "WAF_Prefetch"
+    response_object    = "WAF_Response"
+  }
+
+  force_destroy = true
+}
+
+data "fastly_waf_rules" "owasp" {
+  publishers = ["owasp"]
+}
+
+resource "fastly_service_waf_configuration_v1" "waf" {
+  waf_id                          = fastly_service_v1.demo.waf[0].waf_id
+  http_violation_score_threshold  = 202
+
+  dynamic "rule" {
+    for_each = data.fastly_waf_rules.owasp.rules
+    content {
+      modsec_rule_id = rule.value.modsec_rule_id
+      # Rule revision field ommitted.
+      status         = lookup(var.individual_rules, rule.value.modsec_rule_id, lookup(var.type_status, rule.value.type, "log"))
+    }
+  }
+}
+# This output contains the WAF's active rules set. This can be useful for identifying which revision is active for each WAF rule.
+output "rules" {
+  value = fastly_service_waf_configuration_v1.waf.rule
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported: