Add k8s_cache external plugin (#305)

Signed-off-by: Lennart Ackermans <[email protected]>

Author: lennartack

content/explugins/k8s_cache.md

@@ -0,0 +1,78 @@
++++
+title = "k8s_cache"
+description = "*k8s_cache* is a caching plugin with early refreshes for specified pods"
+weight = 10
+tags = [  "plugin" , "k8s", "cache" ]
+categories = [ "plugin", "external" ]
+date = "2024-04-24T15:20:00+02:00"
+repo = "https://github.com/delta10/k8s_cache"
+home = "https://github.com/delta10/k8s_cache#readme"
++++
+
+## Description
+
+This is a fork of [cache](https://github.com/coredns/coredns/tree/master/plugin/cache). It
+adds an option to send a refreshed positive cache item first to pods with the label
+`k8s-cache.coredns.io/early-refresh=true`. Other pods get it only after a specified
+duration. This makes it possible to implement stable NetworkPolicy whitelists on the basis
+of domain names that are resolved with DNS, using [Stable FQDNNetworkPolicies](https://github.com/delta10/fqdnnetworkpolicies).
+
+The implementation uses an additional cache store called the "late cache", which is
+shifted a number of seconds. On expiration, items in the late cache are replaced with
+items from the early cache if they exist. When a request comes in, the plugin normally
+checks first if the response is cached in the late cache, then in the early cache. If the
+source IP matches a pod with the label `k8s-cache.coredns.io/early-refresh=true`, the late
+cache is skipped and the early cache consulted immediately.
+
+This plugin is intended as a replacement of the *cache* plugin and should not be used in
+combination with it.
+
+We will keep the code of this plugin in sync with *cache* as best as we can.
+
+## Syntax
+
+~~~ txt
+k8s_cache [TTL] [ZONES...] {
+    earlyrefresh [DURATION]
+    success CAPACITY [TTL] [MINTTL]
+    denial CAPACITY [TTL] [MINTTL]
+    prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
+    serve_stale [DURATION] [REFRESH_MODE]
+    servfail DURATION
+    disable success|denial [ZONES...]
+    keepttl
+}
+~~~
+
+For details, see the [cache documentation](https://coredns.io/plugins/cache/). This plugin
+adds one argument and changes the meaning of some other arguments slightly.
+
+* `earlyrefresh` Set the **DURATION** (e.g., "5s") before which `early-refresh` pods get a
+fresh reply. This option actually ***increases*** the cache duration of successful
+responses for pods not having the early refresh label. Each client receives the current
+cache duration *for it* as TTL response.
+* `prefetch` Works as in *cache*, but it uses the expiration time of the early cache to
+calculate whether prefetches should be done.
+* `serve_stale` Works as in *cache*, but **DURATION** is counted from the expiration of
+the early cache. For positive responses cached in the late cache, `serve_stale` starts
+taking effect only when the late cache expires. After the late cache has expired, stale
+serving will continue for **DURATION** minus the duration of `earlyrefresh`. Pods having
+the early refresh label will never be served stale responses.
+
+## Examples
+
+Keep a positive and negative cache size of 10000 (default) and send cache refreshes 5
+seconds earlier to pods with the early refresh label.
+
+~~~ corefile
+.:5300 {
+  k8s_cache {
+    success 10000
+    denial 10000
+    earlyrefresh 5s
+  }
+  forward . 8.8.8.8
+}
+~~~
+
+For general caching examples, see the [cache documentation](https://coredns.io/plugins/cache/).