From 595f63ea94f5afbceadbe36d25fdc83bef375e49 Mon Sep 17 00:00:00 2001
From: Jesse Dohmann <jdohmann@redhat.com>
Date: Mon, 17 Oct 2022 16:47:14 -0500
Subject: [PATCH] OSDOCS-3860: add dns cache tuning

---
 modules/nw-dns-cache-tuning.adoc | 40 ++++++++++++++++++++++++++++++++
 networking/dns-operator.adoc     |  2 ++
 2 files changed, 42 insertions(+)
 create mode 100644 modules/nw-dns-cache-tuning.adoc

diff --git a/modules/nw-dns-cache-tuning.adoc b/modules/nw-dns-cache-tuning.adoc
new file mode 100644
index 0000000000..a0240676a9
--- /dev/null
+++ b/modules/nw-dns-cache-tuning.adoc
@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+// * networking/dns-operator.adoc
+
+:_content-type: PROCEDURE
+[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.
+
+.Procedure
+
+. Edit the DNS Operator object named `default` by running the following command:
++
+[source,terminal]
+----
+$ oc edit dns.operator.openshift.io/default
+----
+
+. Modify the time-to-live (TTL) caching values:
++
+.Configuring DNS caching
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: DNS
+metadata:
+  name: default
+spec:
+  cache:
+    successTTL: 1h <1>
+    denialTTL: 0.5h10m <2>
+----
++
+<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.
++
+[WARNING]
+====
+Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.
+====
diff --git a/networking/dns-operator.adoc b/networking/dns-operator.adoc
index 145ff9b044..9470ba67c1 100644
--- a/networking/dns-operator.adoc
+++ b/networking/dns-operator.adoc
@@ -27,3 +27,5 @@ include::modules/nw-dns-operator-logs.adoc[leveloffset=+1]
 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]