Description

This is a fork of 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.

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

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. 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.

.:5300 {
  k8s_cache {
    success 10000
    denial 10000
    earlyrefresh 5s
  }
  forward . 8.8.8.8
}

For general caching examples, see the cache documentation.