diff --git a/modules/configuring-dns-forwarding-with-tls.adoc b/modules/configuring-dns-forwarding-with-tls.adoc new file mode 100644 index 000000000000..3611175c7522 --- /dev/null +++ b/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]. diff --git a/modules/nw-controlling-dns-pod-placement.adoc b/modules/nw-controlling-dns-pod-placement.adoc index 7dd7f5b29dea..b813a5af0ddb 100644 --- a/modules/nw-controlling-dns-pod-placement.adoc +++ b/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`: + diff --git a/modules/nw-dns-cache-tuning.adoc b/modules/nw-dns-cache-tuning.adoc index 0bcd1a485879..c4c3f1d680b9 100644 --- a/modules/nw-dns-cache-tuning.adoc +++ b/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]. diff --git a/modules/nw-dns-forward.adoc b/modules/nw-dns-forward.adoc index 1dd367019c7c..8729a6f8c920 100644 --- a/modules/nw-dns-forward.adoc +++ b/modules/nw-dns-forward.adoc @@ -8,7 +8,7 @@ You can use DNS forwarding to override the default forwarding configuration in the `/etc/resolv.conf` file in the following ways: -* Specify name servers for every zone. If the forwarded zone is the Ingress domain managed by {product-title}, then the upstream name server must be authorized for the domain. +* Specify name servers (`spec.servers`) for every zone. If the forwarded zone is the ingress domain managed by {product-title}, then the upstream name server must be authorized for the domain. + ifdef::openshift-rosa,openshift-dedicated[] [IMPORTANT] @@ -17,7 +17,7 @@ You must specify at least one zone. Otherwise, your cluster can lose functionali ==== endif::[] + -* Provide a list of upstream DNS servers. +* Provide a list of upstream DNS servers (`spec.upstreamResolvers`). * Change the default forwarding policy. [NOTE] @@ -34,7 +34,7 @@ A DNS forwarding configuration for the default domain can have both the default $ oc edit dns.operator/default ---- + -After you issue the previous command, the Operator creates and updates the config map named `dns-default` with additional server configuration blocks based on `Server`. +After you issue the previous command, the Operator creates and updates the config map named `dns-default` with additional server configuration blocks based on `spec.servers`. ifdef::openshift-rosa,openshift-dedicated[] + [IMPORTANT] @@ -53,10 +53,16 @@ kind: DNS metadata: name: default spec: + cache: + negativeTTL: 0s + positiveTTL: 0s + logLevel: Normal + nodePlacement: {} + operatorLogLevel: Normal servers: - name: example-server <1> - zones: <2> - - example.com + zones: + - example.com <2> forwardPlugin: policy: Random <3> upstreams: <4> @@ -64,130 +70,30 @@ spec: - 2.2.2.2:5353 upstreamResolvers: <5> policy: Random <6> - upstreams: <7> - - type: SystemResolvConf <8> + protocolStrategy: "" <7> + transportConfig: {} <8> + upstreams: + - type: SystemResolvConf <9> - type: Network - address: 1.2.3.4 <9> - port: 53 <10> + address: 1.2.3.4 <10> + port: 53 <11> + status: + clusterDomain: cluster.local + clusterIP: x.y.z.10 + conditions: + ... ---- <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. -<3> Defines the policy to select upstream resolvers. Default value is `Random`. You can also use the values `RoundRobin`, and `Sequential`. +<3> Defines the policy to select upstream resolvers listed in the `forwardPlugin`. Default value is `Random`. You can also use the values `RoundRobin`, and `Sequential`. <4> A maximum of 15 `upstreams` is allowed per `forwardPlugin`. -<5> 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`. -<6> Determines the order in which upstream servers are selected for querying. You can specify one of these values: `Random`, `RoundRobin`, or `Sequential`. The default value is `Sequential`. -<7> Optional. You can use it to provide upstream resolvers. -<8> You can specify two types of `upstreams` - `SystemResolvConf` and `Network`. `SystemResolvConf` configures the upstream to use `/etc/resolv.conf` and `Network` defines a `Networkresolver`. You can specify one or both. -<9> If the specified type is `Network`, you must provide an IP address. The `address` field must be a valid IPv4 or IPv6 address. -<10> If the specified type is `Network`, you can optionally provide a port. The `port` field must have a value between `1` and `65535`. If you do not specify a port for the upstream, by default port 853 is tried. - -. Optional: 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. -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::[] -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: <2> - - example.com - 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`. -By default, 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. -<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. You can 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> `Network` type indicates that this upstream resolver should handle forwarded requests separately from the upstream resolvers listed in `/etc/resolv.conf`. Only the `Network` type is allowed when using TLS and you must provide an IP address. -<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, by default port 853 is tried. -+ -[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 previous sample DNS -[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. +<5> You can use `upstreamResolvers` to override the default forwarding 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 declared in `/etc/resolv.conf`. +<6> Determines the order in which upstream servers listed in `upstreams` are selected for querying. You can specify one of these values: `Random`, `RoundRobin`, or `Sequential`. The default value is `Sequential`. +<7> When omitted, the platform chooses a default, normally the protocol of the original client request. Set to `TCP` to specify that the platform should use TCP for all upstream DNS requests, even if the client request uses UDP. +<8> Used to configure the transport type, server name, and optional custom CA or CA bundle to use when forwarding DNS requests to an upstream resolver. +<9> You can specify two types of `upstreams`: `SystemResolvConf` or `Network`. `SystemResolvConf` configures the upstream to use `/etc/resolv.conf` and `Network` defines a `Networkresolver`. You can specify one or both. +<10> If the specified type is `Network`, you must provide an IP address. The `address` field must be a valid IPv4 or IPv6 address. +<11> If the specified type is `Network`, you can optionally provide a port. The `port` field must have a value between `1` and `65535`. If you do not specify a port for the upstream, the default port is 853. [role="_additional-resources"] .Additional resources diff --git a/modules/nw-dns-loglevel.adoc b/modules/nw-dns-loglevel.adoc index e530c9597b87..8c2d1b3cbde7 100644 --- a/modules/nw-dns-loglevel.adoc +++ b/modules/nw-dns-loglevel.adoc @@ -5,11 +5,11 @@ [id="nw-dns-loglevel_{context}"] = Setting the CoreDNS log level -You can configure the CoreDNS log level to determine the amount of detail in logged error messages. The valid values for CoreDNS log level are `Normal`, `Debug`, and `Trace`. The default `logLevel` is `Normal`. +Log levels for CoreDNS and the CoreDNS Operator are set by using different methods. You can configure the CoreDNS log level to determine the amount of detail in logged error messages. The valid values for CoreDNS log level are `Normal`, `Debug`, and `Trace`. The default `logLevel` is `Normal`. [NOTE] ==== -The errors plugin is always enabled. The following `logLevel` settings report different error responses: +The CoreDNS error log level is always enabled. The following log level settings report different error responses: * `logLevel`: `Normal` enables the "errors" class: `log . { class error }`. @@ -42,3 +42,13 @@ $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"logLevel":"Trace"}} ---- $ oc get configmap/dns-default -n openshift-dns -o yaml ---- ++ +For example, after setting the `logLevel` to `Trace`, you should see this stanza in each server block: ++ +[source,yaml] +---- +errors +log . { + class all +} +---- diff --git a/modules/nw-dns-operator-logs.adoc b/modules/nw-dns-operator-logs.adoc index 783bd474c9ad..e39d0ef406be 100644 --- a/modules/nw-dns-operator-logs.adoc +++ b/modules/nw-dns-operator-logs.adoc @@ -4,13 +4,14 @@ :_mod-docs-content-type: PROCEDURE [id="nw-dns-operator-logs_{context}"] -= DNS Operator logs += Viewing DNS Operator logs You can view DNS Operator logs by using the `oc logs` command. .Procedure -View the logs of the DNS Operator: +* View the logs of the DNS Operator: ++ [source,terminal] ---- $ oc logs -n openshift-dns-operator deployment/dns-operator -c dns-operator diff --git a/modules/nw-dns-operator-managementState.adoc b/modules/nw-dns-operator-managementState.adoc index 5b4907318031..e4d7a0c6b197 100644 --- a/modules/nw-dns-operator-managementState.adoc +++ b/modules/nw-dns-operator-managementState.adoc @@ -6,19 +6,37 @@ [id="nw-dns-operator-managementState_{context}"] = Changing the DNS Operator managementState -DNS manages the CoreDNS component to provide a name resolution service for pods and services in the cluster. The `managementState` of the DNS Operator is set to `Managed` by default, which means that the DNS Operator is actively managing its resources. You can change it to `Unmanaged`, which means the DNS Operator is not managing its resources. +The DNS Operator manages the CoreDNS component to provide a name resolution service for pods and services in the cluster. The `managementState` of the DNS Operator is set to `Managed` by default, which means that the DNS Operator is actively managing its resources. You can change it to `Unmanaged`, which means the DNS Operator is not managing its resources. The following are use cases for changing the DNS Operator `managementState`: -* You are a developer and want to test a configuration change to see if it fixes an issue in CoreDNS. You can stop the DNS Operator from overwriting the fix by setting the `managementState` to `Unmanaged`. +* You are a developer and want to test a configuration change to see if it fixes an issue in CoreDNS. You can stop the DNS Operator from overwriting the configuration change by setting the `managementState` to `Unmanaged`. * You are a cluster administrator and have reported an issue with CoreDNS, but need to apply a workaround until the issue is fixed. You can set the `managementState` field of the DNS Operator to `Unmanaged` to apply the workaround. .Procedure -* Change `managementState` DNS Operator: +. Change `managementState` to `Unmanaged` in the DNS Operator: + [source,terminal] ---- oc patch dns.operator.openshift.io default --type merge --patch '{"spec":{"managementState":"Unmanaged"}}' ---- + +. Review `managementState` of the DNS Operator using the `jsonpath` command line JSON parser: ++ +[source,terminal] +---- +$ oc get dns.operator.openshift.io default -ojsonpath='{.spec.managementState}' +---- ++ +.Example output +[source,terminal] +---- +"Unmanaged" +---- + +[NOTE] +==== +You cannot upgrade while the `managementState` is set to `Unmanaged`. +==== diff --git a/modules/nw-dns-operator-status.adoc b/modules/nw-dns-operator-status.adoc index 5f46df26dbcf..634c111c6033 100644 --- a/modules/nw-dns-operator-status.adoc +++ b/modules/nw-dns-operator-status.adoc @@ -4,15 +4,43 @@ :_mod-docs-content-type: PROCEDURE [id="nw-dns-operator-status_{context}"] -= DNS Operator status += Checking DNS Operator status You can inspect the status and view the details of the DNS Operator using the `oc describe` command. .Procedure -View the status of the DNS Operator: +* View the status of the DNS Operator: ++ [source,terminal] ---- $ oc describe clusteroperators/dns ---- ++ +Though the messages and spelling might vary in a specific release, the expected status output looks like: ++ +[source,terminal] +---- +Status: + Conditions: + Last Transition Time: + Message: DNS "default" is available. + Reason: AsExpected + Status: True + Type: Available + Last Transition Time: + Message: Desired and current number of DNSes are equal + Reason: AsExpected + Status: False + Type: Progressing + Last Transition Time: + Reason: DNSNotDegraded + Status: False + Type: Degraded + Last Transition Time: + Message: DNS default is upgradeable: DNS Operator can be upgraded + Reason: DNSUpgradeable + Status: True + Type: Upgradeable +---- diff --git a/modules/nw-dns-operator.adoc b/modules/nw-dns-operator.adoc index 258da1be7cb1..5c265a3652e6 100644 --- a/modules/nw-dns-operator.adoc +++ b/modules/nw-dns-operator.adoc @@ -3,7 +3,7 @@ :_mod-docs-content-type: PROCEDURE [id="nw-dns-operator_{context}"] -= DNS Operator += Checking the status of the DNS Operator The DNS Operator implements the `dns` API from the `operator.openshift.io` API group. The Operator deploys CoreDNS using a daemon set, creates a service for @@ -38,8 +38,8 @@ $ oc get clusteroperator/dns .Example output [source,terminal] ---- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -dns 4.1.0-0.11 True False False 92m +NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE +dns 4.1.15-0.11 True False False 92m ---- + -`AVAILABLE`, `PROGRESSING` and `DEGRADED` provide information about the status of the operator. `AVAILABLE` is `True` when at least 1 pod from the CoreDNS daemon set reports an `Available` status condition. +`AVAILABLE`, `PROGRESSING`, and `DEGRADED` provide information about the status of the Operator. `AVAILABLE` is `True` when at least 1 pod from the CoreDNS daemon set reports an `Available` status condition, and the DNS service has a cluster IP address. diff --git a/modules/nw-dns-operatorloglevel.adoc b/modules/nw-dns-operatorloglevel.adoc index 3942ea4ec498..cfaed7aa4cc8 100644 --- a/modules/nw-dns-operatorloglevel.adoc +++ b/modules/nw-dns-operatorloglevel.adoc @@ -5,7 +5,7 @@ [id="nw-dns-operatorloglevel_{context}"] = Setting the CoreDNS Operator log level -Cluster administrators can configure the Operator log level to more quickly track down OpenShift DNS issues. The valid values for `operatorLogLevel` are `Normal`, `Debug`, and `Trace`. `Trace` has the most detailed information. The default `operatorlogLevel` is `Normal`. There are seven logging levels for issues: Trace, Debug, Info, Warning, Error, Fatal and Panic. After the logging level is set, log entries with that severity or anything above it will be logged. +Log levels for CoreDNS and CoreDNS Operator are set by using different methods. Cluster administrators can configure the Operator log level to more quickly track down OpenShift DNS issues. The valid values for `operatorLogLevel` are `Normal`, `Debug`, and `Trace`. `Trace` has the most detailed information. The default `operatorlogLevel` is `Normal`. There are seven logging levels for Operator issues: Trace, Debug, Info, Warning, Error, Fatal, and Panic. After the logging level is set, log entries with that severity or anything above it will be logged. * `operatorLogLevel: "Normal"` sets `logrus.SetLogLevel("Info")`. @@ -28,3 +28,27 @@ $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"operatorLogLevel":" ---- $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"operatorLogLevel":"Trace"}}' --type=merge ---- + +.Verification + +. To review the resulting change, enter the following command: ++ +[source,terminal] +---- +$ oc get dnses.operator -A -oyaml +---- ++ +You should see two log level entries. The `operatorLogLevel` applies to OpenShift DNS Operator issues, and the `logLevel` applies to the daemonset of CoreDNS pods: ++ +[source,yaml] +---- + logLevel: Trace + operatorLogLevel: Debug +---- + +. To review the logs for the daemonset, enter the following command: ++ +[source,terminal] +---- +$ oc logs -n openshift-dns ds/dns-default +---- diff --git a/modules/nw-dns-view.adoc b/modules/nw-dns-view.adoc index 9f543bbd0b3e..e0165ee018c7 100644 --- a/modules/nw-dns-view.adoc +++ b/modules/nw-dns-view.adoc @@ -37,14 +37,13 @@ qualified pod and service domain names. <2> The Cluster IP is the address pods query for name resolution. The IP is defined as the 10th address in the service CIDR range. -. To find the service CIDR of your cluster, -use the `oc get` command: +. To find the service CIDR range of your cluster, use the `oc get` command: + [source,terminal] ---- $ oc get networks.config/cluster -o jsonpath='{$.status.serviceNetwork}' ---- - ++ .Example output [source,terminal] ---- diff --git a/modules/nw-external-dns-operator-logs.adoc b/modules/nw-external-dns-operator-logs.adoc index c0e5145de22e..c2113318627f 100644 --- a/modules/nw-external-dns-operator-logs.adoc +++ b/modules/nw-external-dns-operator-logs.adoc @@ -3,7 +3,7 @@ :_mod-docs-content-type: PROCEDURE [id="nw-external-dns-operator-logs_{context}"] -= External DNS Operator logs += Viewing External DNS Operator logs You can view External DNS Operator logs by using the `oc logs` command. diff --git a/networking/dns-operator.adoc b/networking/dns-operator.adoc index 563371bc82a6..8d0247356fc3 100644 --- a/networking/dns-operator.adoc +++ b/networking/dns-operator.adoc @@ -6,17 +6,11 @@ include::_attributes/common-attributes.adoc[] toc::[] -The DNS Operator deploys and manages CoreDNS to provide a name resolution -service to pods, enabling DNS-based Kubernetes Service discovery in -{product-title}. +In {product-title}, the DNS Operator deploys and manages a CoreDNS instance to provide a name resolution service to pods inside the cluster, enables DNS-based Kubernetes Service discovery, and resolves internal `cluster.local` names. ifndef::openshift-rosa,openshift-osd[] include::modules/nw-dns-operator.adoc[leveloffset=+1] -include::modules/nw-dns-operator-managementState.adoc[leveloffset=+1] - -include::modules/nw-controlling-dns-pod-placement.adoc[leveloffset=+1] - include::modules/nw-dns-view.adoc[leveloffset=+1] endif::[] @@ -32,4 +26,13 @@ include::modules/nw-dns-loglevel.adoc[leveloffset=+1] include::modules/nw-dns-operatorloglevel.adoc[leveloffset=+1] include::modules/nw-dns-cache-tuning.adoc[leveloffset=+1] + +[id="dns-operator-advanced-tasks"] +== Advanced tasks + +include::modules/nw-dns-operator-managementState.adoc[leveloffset=+2] + +include::modules/nw-controlling-dns-pod-placement.adoc[leveloffset=+2] + +include::modules/configuring-dns-forwarding-with-tls.adoc[leveloffset=+2] endif::[]