Merge pull request #75531 from jldohmann/OSDOCS-6182

OSDOCS-6182: add improved dns resolution TP concept

Author: jldohmann

modules/nw-coredns-egress-firewall.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * networking/openshift_network_security/configuring-egress-firewall-ovn.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-coredns-egress-firewall_{context}"]
+= Improved DNS resolution and resolving wildcard domain names
+
+There might be situations where the IP addresses associated with a DNS record change frequently, or you might want to specify wildcard domain names in your egress firewall policy rules.
+
+In this situation, the OVN-Kubernetes cluster manager creates a `DNSNameResolver` custom resource object for each unique DNS name used in your egress firewall policy rules. This custom resource stores the following information:
+
+:FeatureName: Improved DNS resolution for egress firewall rules
+include::snippets/technology-preview.adoc[]
+
+[source,yaml]
+.Example `DNSNameResolver` CR definition
+----
+apiVersion: networking.openshift.io/v1alpha1
+kind: DNSNameResolver
+spec:
+  name: www.example.com. <1>
+status:
+  resolvedNames:
+  - dnsName: www.example.com. <2>
+    resolvedAddress:
+    - ip: "1.2.3.4" <3>
+      ttlSeconds: 60 <4>
+      lastLookupTime: "2023-08-08T15:07:04Z" <5>
+----
+<1> The DNS name. This can be either a standard DNS name or a wildcard DNS name. For a wildcard DNS name, the DNS name resolution information contains all of the DNS names that match the wildcard DNS name.
+<2> The resolved DNS name matching the `spec.name` field. If the `spec.name` field contains a wildcard DNS name, then multiple `dnsName` entries are created that contain the standard DNS names that match the wildcard DNS name when resolved. If the wildcard DNS name can also be successfully resolved, then this field also stores the wildcard DNS name.
+<3> The current IP addresses associated with the DNS name.
+<4> The last time-to-live (TTL) duration.
+<5> The last lookup time.
+
+If during DNS resolution the DNS name in the query matches any name defined in a `DNSNameResolver` CR, then the previous information is updated accordingly in the CR `status` field. For unsuccessful DNS wildcard name lookups, the request is retried after a default TTL of 30 minutes.
+
+The OVN-Kubernetes cluster manager watches for updates to an `EgressFirewall` custom resource object, and creates, modifies, or deletes `DNSNameResolver` CRs associated with those egress firewall policies when that update occurs.
+
+[WARNING]
+====
+Do not modify `DNSNameResolver` custom resources directly. This can lead to unwanted behavior of your egress firewall.
+====

networking/openshift_network_security/configuring-egress-firewall-ovn.adoc

@@ -9,5 +9,8 @@ toc::[]
 As a cluster administrator, you can create an egress firewall for a project that restricts egress traffic leaving your {product-title} cluster.
 
 include::modules/nw-egressnetworkpolicy-about.adoc[leveloffset=+1]
+
+include::modules/nw-coredns-egress-firewall.adoc[leveloffset=+3]
+
 include::modules/nw-egressnetworkpolicy-object.adoc[leveloffset=+1]
 include::modules/nw-egressnetworkpolicy-create.adoc[leveloffset=+1]