add details about avoiding loadbalanced and none loadbalanced dnspolicy

Signed-off-by: craig <[email protected]> rh-pre-commit.version: 2.2.0 rh-pre-commit.check-secrets: ENABLED
Kuadrant · Nov 27, 2024 · 4b42b3f · 4b42b3f
1 parent 140bbcc
commit 4b42b3f
Showing 1 changed file with 106 additions and 0 deletions.
diff --git a/doc/user-guides/dnspolicy/load-balanced-dns.md b/doc/user-guides/dnspolicy/load-balanced-dns.md
@@ -80,3 +80,109 @@ To see all regions supported by GCP Cloud DNS, please see the official (document
 
 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]
 
+### Moving from none load balanced to load balanced or visa versa
+
+It is possible to update a DNSPolicy that has no load balancing options set to one that has these options set and visa versa. Underneath, the DNS Operator will remove the existing records and replace them with the correct set of records based on your configuration. It is important however that when using DNSPolicy across multiple Gateways that share a hostname, the DNSPolicies targeting a listener with a shared hostname all use a load balancing configuration or all don't use load balancing configuration (IPAddress only). It is invalid to have two DNSPolcies targeting a listener with a shared hostname that use different dns `strategies`. Doing so will cause one of the DNSPolicies to fail to be enforced and report an error.
+
+**Example:**
+
+If you have `gateway1` with listener `example` with a hostname of `example.com` and you have a separate gateway `gateway2` with the same listener definition as `gateway1` (perhaps on a different cluster in a different region), you should ensure that the DNSPolcies targeting these listeners are both using a `loadbalanced` configuration. Failure to do this, will result in one set of records not being published and an error in one of the DNSPolicies. This failure is intended as the record structure between none load balanced and load balanced is completely different and so cannot be brought into a consistent state by the two dns controllers operating on the two different DNSPolicies.  
+
+**Valid Config**
+
+Given a gateway deployed on two different cluster in two different locations:
+
+```yaml
+# example gateway
+kind: Gateway
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: api-gateway
+spec:
+  gatewayClassName: istio
+  listeners:
+    - name: example
+      port: 80
+      hostname: 'api.example.com'
+      protocol: HTTP
+```
+
+```yaml
+# gateway 1
+
+apiVersion: kuadrant.io/v1
+kind: DNSPolicy
+metadata:
+  name: dnspolicy-gateway1
+spec:
+  loadBalancing:
+    weight: 130
+    geo: GEO-EU
+    defaultGeo: true
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: api-gateway
+    sectionName: example
+  providerRefs:
+    - name: aws-provider-credentials
+
+# gateway 2
+
+apiVersion: kuadrant.io/v1
+kind: DNSPolicy
+metadata:
+  name: dnspolicy-gateway2
+spec:
+  loadBalancing:
+    weight: 130
+    geo: GEO-US
+    defaultGeo: false
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: api-gateway
+    sectionName: example
+  providerRefs:
+    - name: aws-provider-credentials
+
+```
+
+**Invalid Config**
+
+```yaml
+# gateway 1
+
+apiVersion: kuadrant.io/v1
+kind: DNSPolicy
+metadata:
+  name: dnspolicy-gateway1
+spec:
+  loadBalancing:
+    weight: 130
+    geo: GEO-EU
+    defaultGeo: true
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: api-gateway
+    sectionName: example
+  providerRefs:
+    - name: aws-provider-credentials
+
+# gateway 2
+
+apiVersion: kuadrant.io/v1
+kind: DNSPolicy
+metadata:
+  name: dnspolicy-gateway2
+spec: #notice no loadbalancing defined
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: api-gateway
+    sectionName: example
+  providerRefs:
+    - name: aws-provider-credentials
+
+```