Merge pull request #73505 from ahardin-rh/DNS-operator-edits

OSDOCS-8651: Edits from content audit

modules/configuring-dns-forwarding-with-tls.adoc

@@ -0,0 +1,129 @@
+// Module included in the following assemblies:
+//
+// * networking/dns-operator.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-dns-forwarding-with-tls_{context}"]
+= Configuring DNS forwarding with TLS
+
+When working in a highly regulated environment, you might need the ability to secure DNS traffic when forwarding requests to upstream resolvers so that you can ensure additional DNS traffic and data privacy.
+
+Be aware that CoreDNS caches forwarded connections for 10 seconds. CoreDNS will hold a TCP connection open for those 10 seconds if no request is issued. With large clusters, ensure that your DNS server is aware that it might get many new connections to hold open because you can initiate a connection per node. Set up your DNS hierarchy accordingly to avoid performance issues.
+ifdef::openshift-rosa,openshift-dedicated[]
+[IMPORTANT]
+====
+When specifying values for the `zones` parameter, ensure that you only forward to specific zones, such as your intranet. You must specify at least one zone. Otherwise, your cluster can lose functionality.
+====
+endif::[]
+
+.Procedure
+
+. Modify the DNS Operator object named `default`:
++
+[source,terminal]
+----
+$ oc edit dns.operator/default
+----
++
+Cluster administrators can configure transport layer security (TLS) for forwarded DNS queries.
++
+.Configuring DNS forwarding with TLS
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: DNS
+metadata:
+  name: default
+spec:
+  servers:
+  - name: example-server <1>
+    zones:
+    - example.com <2>
+    forwardPlugin:
+      transportConfig:
+        transport: TLS <3>
+        tls:
+          caBundle:
+            name: mycacert
+          serverName: dnstls.example.com  <4>
+      policy: Random <5>
+      upstreams: <6>
+      - 1.1.1.1
+      - 2.2.2.2:5353
+  upstreamResolvers: <7>
+    transportConfig:
+      transport: TLS
+      tls:
+        caBundle:
+          name: mycacert
+        serverName: dnstls.example.com
+    upstreams:
+    - type: Network <8>
+      address: 1.2.3.4 <9>
+      port: 53 <10>
+----
+<1> Must comply with the `rfc6335` service name syntax.
+<2> Must conform to the definition of a subdomain in the `rfc1123` service name syntax. The cluster domain, `cluster.local`, is an invalid subdomain for the `zones` field. The cluster domain, `cluster.local`, is an invalid `subdomain` for `zones`.
+<3> When configuring TLS for forwarded DNS queries, set the `transport` field to have the value `TLS`.
+<4> When configuring TLS for forwarded DNS queries, this is a mandatory server name used as part of the server name indication (SNI) to validate the upstream TLS server certificate.
+<5> Defines the policy to select upstream resolvers. Default value is `Random`. You can also use the values `RoundRobin`, and `Sequential`.
+<6> Required. Use it to provide upstream resolvers. A maximum of 15 `upstreams` entries are allowed per `forwardPlugin` entry.
+<7> Optional. You can use it to override the default policy and forward DNS resolution to the specified DNS resolvers (upstream resolvers) for the default domain. If you do not provide any upstream resolvers, the DNS name queries go to the servers in `/etc/resolv.conf`.
+<8> Only the `Network` type is allowed when using TLS and you must provide an IP address. `Network` type indicates that this upstream resolver should handle forwarded requests separately from the upstream resolvers listed in `/etc/resolv.conf`.
+<9> The `address` field must be a valid IPv4 or IPv6 address.
+<10> You can optionally provide a port. The `port` must have a value between `1` and `65535`. If you do not specify a port for the upstream, the default port is 853.
++
+[NOTE]
+====
+If `servers` is undefined or invalid, the config map only contains the default server.
+====
+
+.Verification
+
+. View the config map:
++
+[source,terminal]
+----
+$ oc get configmap/dns-default -n openshift-dns -o yaml
+----
++
+.Sample DNS ConfigMap based on TLS forwarding example
+[source,yaml]
+----
+apiVersion: v1
+data:
+  Corefile: |
+    example.com:5353 {
+        forward . 1.1.1.1 2.2.2.2:5353
+    }
+    bar.com:5353 example.com:5353 {
+        forward . 3.3.3.3 4.4.4.4:5454 <1>
+    }
+    .:5353 {
+        errors
+        health
+        kubernetes cluster.local in-addr.arpa ip6.arpa {
+            pods insecure
+            upstream
+            fallthrough in-addr.arpa ip6.arpa
+        }
+        prometheus :9153
+        forward . /etc/resolv.conf 1.2.3.4:53 {
+            policy Random
+        }
+        cache 30
+        reload
+    }
+kind: ConfigMap
+metadata:
+  labels:
+    dns.operator.openshift.io/owning-dns: default
+  name: dns-default
+  namespace: openshift-dns
+----
+<1> Changes to the `forwardPlugin` triggers a rolling update of the CoreDNS daemon set.
+
+[role="_additional-resources"]
+.Additional resources
+
+* For more information on DNS forwarding, see the link:https://coredns.io/plugins/forward/[CoreDNS forward documentation].

modules/nw-controlling-dns-pod-placement.adoc

@@ -6,38 +6,23 @@
 [id="nw-controlling-dns-pod-placement_{context}"]
 = Controlling DNS pod placement
 
-The DNS Operator has two daemon sets: one for CoreDNS and one for managing the `/etc/hosts` file. The daemon set for `/etc/hosts` must run on every node host to add an entry for the cluster image registry to support pulling images. Security policies can prohibit communication between pairs of nodes, which prevents the daemon set for CoreDNS from running on every node.
+The DNS Operator has two daemon sets: one for CoreDNS called `dns-default` and one for managing the `/etc/hosts` file `called node-resolver`.
 
-As a cluster administrator, you can use a custom node selector to configure the daemon set for CoreDNS to run or not run on certain nodes.
+You might find a need to control which nodes have CoreDNS pods assigned and running, although this is not a common operation. For example, if the cluster administrator has configured security policies that can prohibit communication between pairs of nodes, that would necessitate restricting the set of nodes on which the daemonset for CoreDNS runs. If DNS pods are running on some nodes in the cluster and the nodes where DNS pods are not running have network connectivity to nodes where DNS pods are running, DNS service will be available to all pods.
+
+The `node-resolver` daemon set must run on every node host because it adds an entry for the cluster image registry to support pulling images. The `node-resolver` pods have only one job: to look up the `image-registry.openshift-image-registry.svc` service's cluster IP address and add it to `/etc/hosts` on the node host so that the container runtime can resolve the service name.
 
+As a cluster administrator, you can use a custom node selector to configure the daemon set for CoreDNS to run or not run on certain nodes.
 
 .Prerequisites
 
 * You installed the `oc` CLI.
-* You are logged in to the cluster with a user with `cluster-admin` privileges.
+* You are logged in to the cluster as a user with `cluster-admin` privileges.
+* Your DNS Operator `managementState` is set to `Managed`.
 
 .Procedure
 
-* To prevent communication between certain nodes, configure the `spec.nodePlacement.nodeSelector` API field:
-
-. Modify the DNS Operator object named `default`:
-+
-[source,terminal]
-----
-$ oc edit dns.operator/default
-----
-+
-. Specify a node selector that includes only control plane nodes in the `spec.nodePlacement.nodeSelector` API field:
-+
-[source,yaml]
-----
- spec:
-   nodePlacement:
-     nodeSelector:
-       node-role.kubernetes.io/worker: ""
-----
-
-* To allow the daemon set for CoreDNS to run on nodes, configure a taint and toleration:
+* To allow the daemon set for CoreDNS to run on certain nodes, configure a taint and toleration:
 +
 . Modify the DNS Operator object named `default`:
 +

modules/nw-dns-cache-tuning.adoc

@@ -5,7 +5,12 @@
 [id="nw-dns-cache-tuning_{context}"]
 = Tuning the CoreDNS cache
 
-You can configure the maximum duration of both successful or unsuccessful caching, also known as positive or negative caching respectively, done by CoreDNS. Tuning the duration of caching of DNS query responses can reduce the load for any upstream DNS resolvers.
+For CoreDNS, you can configure the maximum duration of both successful or unsuccessful caching, also known respectively as positive or negative caching. Tuning the cache duration of DNS query responses can reduce the load for any upstream DNS resolvers.
+
+[WARNING]
+====
+Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.
+====
 
 .Procedure
 
@@ -33,8 +38,26 @@ spec:
 +
 <1> The string value `1h` is converted to its respective number of seconds by CoreDNS. If this field is omitted, the value is assumed to be `0s` and the cluster uses the internal default value of `900s` as a fallback.
 <2> The string value can be a combination of units such as `0.5h10m` and is converted to its respective number of seconds by CoreDNS. If this field is omitted, the value is assumed to be `0s` and the cluster uses the internal default value of `30s` as a fallback.
+
+.Verification
+
+. To review the change, look at the config map again by running the following command:
 +
-[WARNING]
-====
-Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.
-====
+[source,terminal]
+----
+oc get configmap/dns-default -n openshift-dns -o yaml
+----
+
+. Verify that you see entries that look like the following example:
++
+[source,yaml]
+----
+       cache 3600 {
+            denial 9984 2400
+        }
+----
+
+[role="_additional-resources"]
+.Additional resources
+
+For more information on caching, see link:https://coredns.io/plugins/cache/[CoreDNS cache].