codereview: improve config param documentation

Signed-off-by: Steve Kriss <krisss@vmware.com>

examples/contour/01-contour-config.yaml

@@ -99,3 +99,7 @@ data:
     #   Configure the number of additional ingress proxy hops from the
     #   right side of the x-forwarded-for HTTP header to trust.
     #   num-trusted-hops: 0
+    # rateLimitService:
+    #   extensionService: projectcontour/ratelimit
+    #   domain: contour
+    #   failOpen: false

examples/render/contour.yaml

@@ -133,6 +133,10 @@ data:
     #   Configure the number of additional ingress proxy hops from the
     #   right side of the x-forwarded-for HTTP header to trust.
     #   num-trusted-hops: 0
+    # rateLimitService:
+    #   extensionService: projectcontour/ratelimit
+    #   domain: contour
+    #   failOpen: false
 
 ---
 apiVersion: apiextensions.k8s.io/v1

pkg/config/parameters.go

@@ -486,7 +486,8 @@ type RateLimitService struct {
 	Domain string `yaml:"domain,omitempty"`
 
 	// FailOpen defines whether to allow requests to proceed when the
-	// Rate Limit Service fails to respond properly.
+	// Rate Limit Service fails to respond with a valid rate limit
+	// decision within the timeout defined on the extension service.
 	FailOpen bool `yaml:"failOpen,omitempty"`
 }
 

site/docs/main/configuration.md

@@ -84,6 +84,7 @@ Where Contour settings can also be specified with command-line flags, the comman
 | network | NetworkConfig | | The [network configuration](#network-configuration). |
 | server | ServerConfig |  | The [server configuration](#server-configuration) for `contour serve` command. |
 | gateway | GatewayConfig |  | The [service-apis Gateway configuration](#gateway-configuration). |
+| rateLimitService | RateLimitServiceConfig | | The [rate limit service configuration](#rate-limit-service-configuration). |
 {: class="table thead-dark table-bordered"}
 <br>
 
@@ -191,6 +192,18 @@ The gateway configuration block is used to configure which service-apis Gateway
 {: class="table thead-dark table-bordered"}
 <br>
 
+### Rate Limit Service Configuration
+
+The rate limit service configuration block is used to configure an optional global rate limit service:
+
+| Field Name | Type| Default  | Description |
+|------------|-----|----------|-------------|
+| extensionService | string | <none> | This field identifies the extension service defining the rate limit service, formatted as <namespace>/<name>.  |
+| domain | string | contour | This field defines the rate limit domain to pass to the rate limit service.  |
+| failOpen | bool | false | This field defines whether to allow requests to proceed when the rate limit service fails to respond with a valid rate limit decision within the timeout defined on the extension service.  |
+{: class="table thead-dark table-bordered"}
+<br>
+
 ### Configuration Example
 
 The following is an example ConfigMap with configuration file included:
@@ -294,6 +307,11 @@ data:
     #   Configure the number of additional ingress proxy hops from the
     #   right side of the x-forwarded-for HTTP header to trust.
     #   num-trusted-hops: 0
+    #
+    # rateLimitService:
+    #   extensionService: projectcontour/ratelimit
+    #   domain: contour
+    #   failOpen: false
 ```
 
 _Note:_ The default example `contour` includes this [file][1] for easy deployment of Contour.