codereview: improve docs

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

examples/contour/01-contour-config.yaml

@@ -106,7 +106,17 @@ 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
+    #
+    # Configure an optional global rate limit service.
     # rateLimitService:
+    #   Identifies the extension service defining the rate limit service,
+    #   formatted as <namespace>/<name>.
     #   extensionService: projectcontour/ratelimit
+    #   Defines the rate limit domain to pass to the rate limit service.
+    #   Acts as a container for a set of rate limit definitions within
+    #   the RLS.
     #   domain: contour
+    #   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.
     #   failOpen: false

examples/render/contour.yaml

@@ -140,9 +140,19 @@ 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
+    #
+    # Configure an optional global rate limit service.
     # rateLimitService:
+    #   Identifies the extension service defining the rate limit service,
+    #   formatted as <namespace>/<name>.
     #   extensionService: projectcontour/ratelimit
+    #   Defines the rate limit domain to pass to the rate limit service.
+    #   Acts as a container for a set of rate limit definitions within
+    #   the RLS.
     #   domain: contour
+    #   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.
     #   failOpen: false
 
 ---

site/_guides/global-rate-limiting.md

@@ -24,6 +24,13 @@ This guide assumes that you have:
 ## Deploy an RLS
 
 For this guide, we'll deploy the [Envoy rate limit service][4] as our RLS.
+Per the project's README:
+
+> The rate limit service is a Go/gRPC service designed to enable generic rate limit scenarios from different types of applications.
+> Applications request a rate limit decision based on a domain and a set of descriptors.
+> The service reads the configuration from disk via [runtime][10], composes a cache key, and talks to the Redis cache.
+> A decision is then returned to the caller.
+
 However, any service that implements the [RateLimitService gRPC interface][5] is supported by Contour/Envoy.
 
 Create a config map with [the ratelimit service configuration][6]:
@@ -425,3 +432,4 @@ The YAML used in this guide is available [in the Contour repository][9].
 [7]: /docs/{{site.latest}}/config/rate-limiting/
 [8]: /docs/{{site.latest}}/config/api/
 [9]: {{site.github.repository_url}}/tree/main/examples/ratelimit
+[10]: https://github.com/lyft/goruntime

site/docs/main/config/rate-limiting.md

@@ -177,8 +177,15 @@ spec:
 Now add a reference to it in the Contour config file:
 ```yaml
 rateLimitService:
+  # The namespace/name of the extension service.
   extensionService: projectcontour/ratelimit
+  # The domain value to pass to the RLS for all rate limit
+  # requests. Acts as a container for a set of rate limit
+  # definitions within the RLS.
   domain: contour
+  # 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.
   failOpen: true
 ```
 

site/docs/main/configuration.md

@@ -200,7 +200,7 @@ The rate limit service configuration block is used to configure an optional glob
 | 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.  |
+| domain | string | contour | This field defines the rate limit domain value to pass to the rate limit service. Acts as a container for a set of rate limit definitions within the RLS.  |
 | 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>