Skip to content

Commit 8c34bf8

Browse files
ahardin-rhahardin-rh
committed
OSDOCS-8651: Edits from content audit
1 parent bcba852 commit 8c34bf8

13 files changed

+303
-177
lines changed

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/dns-operator.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="configuring-dns-forwarding-with-tls_{context}"]
7+
= Configuring DNS forwarding with TLS
8+
9+
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.
10+
11+
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.
12+
ifdef::openshift-rosa,openshift-dedicated[]
13+
[IMPORTANT]
14+
====
15+
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.
16+
====
17+
endif::[]
18+
19+
.Procedure
20+
21+
. Modify the DNS Operator object named `default`:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc edit dns.operator/default
26+
----
27+
+
28+
Cluster administrators can configure transport layer security (TLS) for forwarded DNS queries.
29+
+
30+
.Configuring DNS forwarding with TLS
31+
[source,yaml]
32+
----
33+
apiVersion: operator.openshift.io/v1
34+
kind: DNS
35+
metadata:
36+
name: default
37+
spec:
38+
servers:
39+
- name: example-server <1>
40+
zones:
41+
- example.com <2>
42+
forwardPlugin:
43+
transportConfig:
44+
transport: TLS <3>
45+
tls:
46+
caBundle:
47+
name: mycacert
48+
serverName: dnstls.example.com <4>
49+
policy: Random <5>
50+
upstreams: <6>
51+
- 1.1.1.1
52+
- 2.2.2.2:5353
53+
upstreamResolvers: <7>
54+
transportConfig:
55+
transport: TLS
56+
tls:
57+
caBundle:
58+
name: mycacert
59+
serverName: dnstls.example.com
60+
upstreams:
61+
- type: Network <8>
62+
address: 1.2.3.4 <9>
63+
port: 53 <10>
64+
----
65+
<1> Must comply with the `rfc6335` service name syntax.
66+
<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`.
67+
<3> When configuring TLS for forwarded DNS queries, set the `transport` field to have the value `TLS`.
68+
<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.
69+
<5> Defines the policy to select upstream resolvers. Default value is `Random`. You can also use the values `RoundRobin`, and `Sequential`.
70+
<6> Required. Use it to provide upstream resolvers. A maximum of 15 `upstreams` entries are allowed per `forwardPlugin` entry.
71+
<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`.
72+
<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`.
73+
<9> The `address` field must be a valid IPv4 or IPv6 address.
74+
<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.
75+
+
76+
[NOTE]
77+
====
78+
If `servers` is undefined or invalid, the config map only contains the default server.
79+
====
80+
81+
.Verification
82+
83+
. View the config map:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc get configmap/dns-default -n openshift-dns -o yaml
88+
----
89+
+
90+
.Sample DNS ConfigMap based on TLS forwarding example
91+
[source,yaml]
92+
----
93+
apiVersion: v1
94+
data:
95+
Corefile: |
96+
example.com:5353 {
97+
forward . 1.1.1.1 2.2.2.2:5353
98+
}
99+
bar.com:5353 example.com:5353 {
100+
forward . 3.3.3.3 4.4.4.4:5454 <1>
101+
}
102+
.:5353 {
103+
errors
104+
health
105+
kubernetes cluster.local in-addr.arpa ip6.arpa {
106+
pods insecure
107+
upstream
108+
fallthrough in-addr.arpa ip6.arpa
109+
}
110+
prometheus :9153
111+
forward . /etc/resolv.conf 1.2.3.4:53 {
112+
policy Random
113+
}
114+
cache 30
115+
reload
116+
}
117+
kind: ConfigMap
118+
metadata:
119+
labels:
120+
dns.operator.openshift.io/owning-dns: default
121+
name: dns-default
122+
namespace: openshift-dns
123+
----
124+
<1> Changes to the `forwardPlugin` triggers a rolling update of the CoreDNS daemon set.
125+
126+
[role="_additional-resources"]
127+
.Additional resources
128+
129+
* For more information on DNS forwarding, see the link:https://coredns.io/plugins/forward/[CoreDNS forward documentation].

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

Lines changed: 8 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,23 @@
66
[id="nw-controlling-dns-pod-placement_{context}"]
77
= Controlling DNS pod placement
88

9-
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.
9+
The DNS Operator has two daemon sets: one for CoreDNS called `dns-default` and one for managing the `/etc/hosts` file `called node-resolver`.
1010

11-
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.
11+
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.
12+
13+
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.
1214

15+
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.
1316

1417
.Prerequisites
1518

1619
* You installed the `oc` CLI.
17-
* You are logged in to the cluster with a user with `cluster-admin` privileges.
20+
* You are logged in to the cluster as a user with `cluster-admin` privileges.
21+
* Your DNS Operator `managementState` is set to `Managed`.
1822
1923
.Procedure
2024

21-
* To prevent communication between certain nodes, configure the `spec.nodePlacement.nodeSelector` API field:
22-
23-
. Modify the DNS Operator object named `default`:
24-
+
25-
[source,terminal]
26-
----
27-
$ oc edit dns.operator/default
28-
----
29-
+
30-
. Specify a node selector that includes only control plane nodes in the `spec.nodePlacement.nodeSelector` API field:
31-
+
32-
[source,yaml]
33-
----
34-
spec:
35-
nodePlacement:
36-
nodeSelector:
37-
node-role.kubernetes.io/worker: ""
38-
----
39-
40-
* To allow the daemon set for CoreDNS to run on nodes, configure a taint and toleration:
25+
* To allow the daemon set for CoreDNS to run on certain nodes, configure a taint and toleration:
4126
+
4227
. Modify the DNS Operator object named `default`:
4328
+

‎modules/nw-dns-cache-tuning.adoc

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@
55
[id="nw-dns-cache-tuning_{context}"]
66
= Tuning the CoreDNS cache
77

8-
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.
8+
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.
9+
10+
[WARNING]
11+
====
12+
Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.
13+
====
914

1015
.Procedure
1116

@@ -33,8 +38,26 @@ spec:
3338
+
3439
<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.
3540
<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.
41+
42+
.Verification
43+
44+
. To review the change, look at the config map again by running the following command:
3645
+
37-
[WARNING]
38-
====
39-
Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.
40-
====
46+
[source,terminal]
47+
----
48+
oc get configmap/dns-default -n openshift-dns -o yaml
49+
----
50+
51+
. Verify that you see entries that look like the following example:
52+
+
53+
[source,yaml]
54+
----
55+
cache 3600 {
56+
denial 9984 2400
57+
}
58+
----
59+
60+
[role="_additional-resources"]
61+
.Additional resources
62+
63+
For more information on caching, see link:https://coredns.io/plugins/cache/[CoreDNS cache].

0 commit comments

Comments
 (0)