<commit_before>// Module included in the following assemblies:
//
// * networking/dns-operator.adoc

[id="nw-dns-forward_{context}"]
= Using DNS forwarding

You can use DNS forwarding to override the forwarding configuration identified in `/etc/resolv.conf` on a per-zone basis by specifying which name server should be used for a given zone. If the forwarded zone is the Ingress domain managed by {product-title}, then the upstream name server must be authorized for the domain.

.Procedure

. Modify the DNS Operator object named `default`:
+
[source,terminal]
----
$ oc edit dns.operator/default
----
+
This allows the Operator to create and update the ConfigMap named `dns-default` with additional server configuration blocks based on `Server`. If none of the servers has a zone that matches the query, then name resolution falls back to the name servers that are specified in `/etc/resolv.conf`.
+
.Sample DNS
[source,yaml]
----
apiVersion: operator.openshift.io/v1
kind: DNS
metadata:
  name: default
spec:
  servers:
  - name: foo-server <1>
    zones: <2>
      - foo.com
    forwardPlugin:
      upstreams: <3>
        - 1.1.1.1
        - 192.168.127.12:5353
  - name: bar-server
    zones:
      - bar.com
      - example.com
    forwardPlugin:
      upstreams:
        - 172.16.17.32
        - 192.168.3.11:5454
----
<1> `name` must comply with the `rfc6335` service name syntax.
<2> `zones` must conform to the definition of a `subdomain` in `rfc1123`. The cluster domain, `cluster.local`, is an invalid `subdomain` for `zones`.
<3> A maximum of 15 `upstreams` is allowed per `forwardPlugin`.
+
[NOTE]
====
If `servers` is undefined or invalid, the ConfigMap only contains the default server.
====
+
. View the ConfigMap:
+
[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: |
    foo.com:5353 {
        forward . 1.1.1.1 192.168.127.12:5353
    }
    bar.com:5353 example.com:5353 {
        forward . 172.16.17.32 192.168.3.11: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 {
            policy sequential
        }
        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.

.Additional resources

* For more information on DNS forwarding, see the link:https://coredns.io/plugins/forward/[CoreDNS forward documentation].
<commit_msg>NE743: document upstream resolvers<commit_after>// Module included in the following assemblies:
//
// * networking/dns-operator.adoc

[id="nw-dns-forward_{context}"]
= Using DNS forwarding

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.
* Provide a list of upstream DNS servers.
* Change the default forwarding policy.

[NOTE]
=====
A DNS forwarding configuration for the default domain can have both the default servers specified in the `/etc/resolv.conf` file and the upstream DNS servers.
=====

.Procedure

. Modify the DNS Operator object named `default`:
+
[source,terminal]
----
$ oc edit dns.operator/default
----
+
This allows the Operator to create and update the ConfigMap named `dns-default` with additional server configuration blocks based on `Server`. If none of the servers has a zone that matches the query, then name resolution falls back to the upstream DNS servers.
+
.Sample DNS
[source,yaml]
----
apiVersion: operator.openshift.io/v1
kind: DNS
metadata:
  name: default
spec:
  servers:
  - name: foo-server <1>
    zones: <2>
      - foo.com
    forwardPlugin:
      upstreams: <3>
        - 1.1.1.1
        - 192.168.127.12:5353
  - name: bar-server
    zones:
      - bar.com
      - example.com
    forwardPlugin:
      upstreams:
        - 172.16.17.32
        - 192.168.3.11:5454
  upstreamResolvers: <4>
    policy: Random <5>
    upstreams: <6>
    - type: SystemResolvConf <7>
    - type: Network
      address: 172.16.58.3 <8>
      port: 53 <9>
----
<1> Must comply with the `rfc6335` service name syntax.
<2> Must conform to the definition of a `subdomain` in `rfc1123`. The cluster domain, `cluster.local`, is an invalid `subdomain` for `zones`.
<3> A maximum of 15 `upstreams` is allowed per `forwardPlugin`.
<4> 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`.
<5> Determines the order in which upstream servers are selected for querying. You can specify one of these values: `Random`, `RoundRobin`, and `Sequential`. The default value is `Sequential`.
<6> Optional. You can use it to provide upstream resolvers.
<7> You can specify two types of `upstreams` - `SystemResolvConf` and `Network`. `SystemResolvConf` is for configuring the upstream to use `/etc/resolv.conf` and `Network` is for defining a `Networkresolver`. You can specify one or both.
<8> If the specified type is `Network`, you must provide an IP address. `address` must be a valid IPv4 or IPv6 address.
<9> If the specified type is `Network`, you can optionally provide a port. `port` must be between 1 and 65535.
+
[NOTE]
====
If `servers` is undefined or invalid, the ConfigMap only contains the default server.
====
+
. View the ConfigMap:
+
[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: |
    foo.com:5353 {
        forward . 1.1.1.1 192.168.127.12:5353
    }
    bar.com:5353 example.com:5353 {
        forward . 172.16.17.32 192.168.3.11: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 172.16.58.3: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.

.Additional resources

* For more information on DNS forwarding, see the link:https://coredns.io/plugins/forward/[CoreDNS forward documentation].

{'fraction_non_alphanumeric': 0.10194795961893928, 'fraction_numerical': 0.041945115882269304, 'mean_word_length': 2.8969529085872576, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 18, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2983627', 'n_tokens_mistral': 2381, 'n_tokens_neox': 2139, 'n_words': 810}