updated load balanced dns doc (#1039)

Signed-off-by: craig <cbrookes@redhat.com>

rh-pre-commit.version: 2.2.0
rh-pre-commit.check-secrets: ENABLED

doc/dns.md

@@ -43,27 +43,33 @@ spec:
    - name: my-aws-credentials
 
   # (optional) loadbalancing specification
-  # use it for providing the specification of how dns will be configured in order to provide balancing of load across multiple clusters
+  # use it for providing the specification of how dns will be configured in order to provide balancing of requests across multiple clusters. If not configured, a simple A or CNAME record will be created. If you have a policy with no loadbalancing defined and want to move to a loadbalanced configuration, you will need to delete and re-create the policy.
   loadBalancing:
-    # default geo to be applied to records
+    # is this the default geo to be applied to records. It is important that you set the default geo flag to true **Only** for the GEO value you wish to act as the catchall GEO, you should not set multiple GEO values as default for a given targeted listener. Example: policy 1 targets listener 1 with a geo of US and sets default to true. Policy 2 targets a listener on another cluster and set the geo to EU and default to false. It is fine for policies in the same default GEO to set the value to true. The main thing is to have only one unique GEO set as the default for any shared listener hostname.
     defaultGeo: true
-    # weighted specification
+    # weighted specification. This will apply the given weight to the records created based on the targeted gateway listeners. If you have multiple gateways that share a listener host, you can set different weight values to influence how much traffic will be brought to a given gateway.
     weight: 100
-    # 
+    # This is the actual GEO location to set for records created by this policy. This can and should be different if you have multiple gateways across multiple geographic areas. 
+
+    # AWS: To see all regions supported by AWS Route 53, please see the official (documentation)[https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-geo.html]. With Route 53 when setting a continent code use a "GEO-" prefix otherwise it will be considered a country code. 
+
+    # GCP: To see all regions supported by GCP Cloud DNS, please see the official (documentation)[https://cloud.google.com/compute/docs/regions-zones]
+
+    #To see the different values you can use for the geo based DNS with Azure take a look at the following (documentation)[https://learn.microsoft.com/en-us/azure/traffic-manager/traffic-manager-geographic-regions]
     geo: IE
 
   # (optional) health check specification
-  # health check probes with the following specification will be created for each DNS target
+  # health check probes with the following specification will be created for each DNS target, these probes constantly check that the endpoint can be reached. They will flag an unhealthy endpoint in the status. If no DNSRecord has yet been published and the endpoint is unhealthy, the record will not be published until the health check passes.
   healthCheck:
-    allowInsecureCertificates: true
-    endpoint: /
-    expectedResponses:
-      - 200
-      - 201
-      - 301
-    failureThreshold: 5
-    port: 443
-    protocol: https
+    # the path on the listener host(s) that you want to check. 
+    path: /health
+    # how many times does the health check need to fail before unhealthy.
+    failureThreshold: 3
+    # how often should it be checked.
+    interval: 5min
+    # additionalHeadersRef is reference to a local secret with a set of key value pairs to be used as headers when sending the health check request.
+    additionalHeadersRef:
+      name: headers
 ```
 
 Check out the [API reference](reference/dnspolicy.md) for a full specification of the DNSPolicy CRD.
@@ -175,6 +181,25 @@ spec:
     name: <Gateway Name>
 ```
 
+### Targeting a specific Listener of a gateway
+
+A DNSPolicy can target a specific listener in a gateway using the `sectionName` property of the targetRef configuration. When you set the `sectionName`, the DNSPolicy will only affect that listener and no others. If you also have another DNSPolicy targeting the entire gateway, the more specific policy targeting the listerner will be the policy that is applied.
+
+```yaml
+apiVersion: kuadrant.io/v1beta2
+kind: DNSPolicy
+metadata:
+  name: <DNSPolicy name>
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: <Gateway Name>
+    sectionName: <myListenerName>
+```
+
+
+
 ### DNSRecord Resource
 
 The DNSPolicy will create a DNSRecord resource for each listener hostname. The DNSPolicy resource uses the status of the Gateway to determine what dns records need to be created based on the clusters it has been placed onto.
@@ -293,5 +318,5 @@ dig echo.apps.hcpapps.net +short
 
 ### Known limitations
 
-* One Gateway can only be targeted by one DNSPolicy.
+* One Gateway can only be targeted by one DNSPolicy unless subsequent DNSPolicies choose to specific a sectionName in their targetRef.
 * DNSPolicies can only target Gateways defined within the same namespace of the DNSPolicy.

doc/user-guides/dnspolicy/dnshealthchecks.md

@@ -25,7 +25,7 @@ kind: DNSPolicy
 metadata:
   name: gateway-dns
 spec:
-  health check:
+  healthCheck:
     failureThreshold: 3
     interval: 5m
     path: /health
@@ -45,7 +45,7 @@ kind: DNSPolicy
 metadata:
   name: my-listener-dns
 spec:
-  health check:
+  healthCheck:
     failureThreshold: 3
     interval: 5m
     path: /ok #different path for this listener
@@ -79,7 +79,7 @@ kind: DNSPolicy
 metadata:
   name: my-listener-dns
 spec:
-  health check:
+  healthCheck:
     additionalHeadersRef: #add the following
       name: healthheaders
     failureThreshold: 3

doc/user-guides/dnspolicy/load-balanced-dns.md

@@ -0,0 +1,82 @@
+# Load Balanced DNS
+
+## Overview
+
+This document will show you how to setup a load balanced DNS configuration using the (DNSPolicy)[https://docs.kuadrant.io/latest/kuadrant-operator/doc/reference/dnspolicy/] API. When we say "load balanced", this means we configure the DNS provider (AWS, GCP etc) to return different gateway/loadbalancer addresses to queries from DNS clients based on specific weighting and geo location configuration.
+
+
+### When should I use a load balanced DNS policy?
+
+It is most useful to use the load balancing options when targeting multiple gateways that share a listener host E.G (api.example.com). It is also perfectly valid to use it when you only have a single gateway; this provides the benefit of allowing you to easily expand beyond this single gateway for a given shared hostname. It is worth knowing that the load balanced DNSpolicy comes with a relatively small additional cost of some added records and lookups during DNS resolution vs a "simple" DNSPolicy with no load balancing specified as the latter only sets up a simple A or CNAME record. So in summary if you expect to need multiple gateways for a given listener host then you should take advantage of the load balanced option.
+
+
+### Important Considerations
+
+- When using a DNSPolicy with a load balanced configuration, all DNSPolicies effecting a listener with the same hostname should have load balanced options set. Without the load balanced configuration, Kuadrant's dns controller will try to set up only a simple A or CNAME record.
+- When setting geographic configuration, only ever set one unique GEO as the default GEO across all instances of DNSPolicy targeting a listener with the same hostname. If you set different defaults for a single listener hostname, the dns controllers will constantly attempt to bring the default into the state they each feel is correct. 
+- If you want different load balancing options for a particular listener in a gateway, you can target that listener directly with DNSPolicy via the targetRef sectionName property.
+- If you do not use the load balanced configuration, a simple single A or CNAME record is set up. Later if you need to move to load balanced, you will need to delete and recreate your policy.
+
+## DNS Provider Setup
+
+A DNSPolicy acts against a target Gateway or a target listener within a gateway by processing the hostnames on the targeted listeners. Using these it can create dns records using the address exposed in the Gateway's status block. In order for Kuadrant's DNS component to do this, it must be able to access and know which DNS provider to use. This is done through the creation of a dns provider secret containing the needed credentials and the provider identifier.
+
+(Learn more about how to setup a DNS Provider)[https://docs.kuadrant.io/latest/dns-operator/docs/provider/]
+
+
+## LoadBalanced DNSPolicy creation and attachment
+
+Once an appropriate provider credential is configured, we can now create and attach a DNSPolicy to start managing DNS for the listeners on our Gateway. Below is an example.
+
+```yaml
+apiVersion: kuadrant.io/v1
+kind: DNSPolicy
+metadata:
+  name: prod-web
+  namespace: ingress-gateway
+spec:
+  targetRef:
+    name: prod-web
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    sectionName: listenerName 
+  providerRef:
+    name: my-aws-credentials 
+  loadBalancing:
+    weight: 120 
+    geo: GEO-EU 
+    defaultGeo: true
+
+```
+
+
+### Load Balancing section
+
+This section must be filled out and indicates to the dns component that the targets of this policy should be setup to handle more than one gateway. It is required to define values for the weighted and geo options. These values are used for the records created by the policy controller based on the target gateway.
+To read more detail about each of the fields in the loadbalanced section take a look at [DNS Overview](https://docs.kuadrant.io/latest/kuadrant-operator/doc/dns/#high-level-example-and-field-definition)
+
+
+
+##### Locations supported per DNS provider
+
+| Supported     | AWS | GCP |
+|---------------|-----|-----|
+| Continents    | :white_check_mark: |  :x: |
+| Country codes | :white_check_mark: |  :x:  |
+| States        | :white_check_mark: |  :x:  |
+| Regions       |  :x:  | :white_check_mark: |  
+
+##### Continents and country codes supported by AWS Route 53
+
+:**Note:** :exclamation: For more information please the official AWS documentation 
+
+To see all regions supported by AWS Route 53, please see the official (documentation)[https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-geo.html]. With Route 53 when setting a continent code use a "GEO-" prefix otherwise it will be considered a country code. 
+
+##### Regions supported by GCP Cloud DNS
+
+To see all regions supported by GCP Cloud DNS, please see the official (documentation)[https://cloud.google.com/compute/docs/regions-zones]
+
+##### Regions and Countries supported by Azure Cloud DNS
+
+To see the different values you can use for the geo based DNS with Azure take a look at the following (documentation)[https://learn.microsoft.com/en-us/azure/traffic-manager/traffic-manager-geographic-regions]
+