cache

README

k8s_cache

Name

k8s_cache - a CoreDNS caching plugin with early refreshes for specified pods

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, using tools such as dns-resolution-operator.

The implementation uses an additional cache store called the "late cache", which is shifted a number of seconds. On expiration, items in the late cached 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
    denail 10000
    earlyrefresh 5s
  }
  forward . 8.8.8.8
}

For general caching examples, see the cache documentation.

Documentation

Overview

Package cache implements a cache.

Index

• Constants
• type Cache
  • func New() *Cache
  • func (c *Cache) Name() string
  • func (c *Cache) NeedEarlyRefresh(state request.Request) bool
  • func (c *Cache) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type CacheBackend
  • func NewBackend() *CacheBackend
• type ResponseWriter
  • func (w *ResponseWriter) RemoteAddr() net.Addr
  • func (w *ResponseWriter) Write(buf []byte) (int, error)
  • func (w *ResponseWriter) WriteMsg(res *dns.Msg) error

Constants

const (

	// Success is the class for caching positive caching.
	Success = "success"
	// Denial is the class defined for negative caching.
	Denial = "denial"
)

Types

type Cache

type Cache struct {
	*CacheBackend
	// contains filtered or unexported fields
}

func New

func New() *Cache

func (*Cache) Name

func (c *Cache) Name() string

Name implements the Handler interface.

func (*Cache) NeedEarlyRefresh

func (c *Cache) NeedEarlyRefresh(state request.Request) bool

func (*Cache) ServeDNS

func (c *Cache) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the plugin.Handler interface.

type CacheBackend

type CacheBackend struct {
	Next  plugin.Handler
	Zones []string
	// contains filtered or unexported fields
}

Cache is a plugin that looks up responses in a cache and caches replies. It has a success and a denial of existence cache.

func NewBackend

func NewBackend() *CacheBackend

New returns an initialized Cache with default settings. It's up to the caller to set the Next handler.

type ResponseWriter

type ResponseWriter struct {
	dns.ResponseWriter
	*Cache
	// contains filtered or unexported fields
}

ResponseWriter is a response writer that caches the reply message.

func (*ResponseWriter) RemoteAddr

func (w *ResponseWriter) RemoteAddr() net.Addr

RemoteAddr implements the dns.ResponseWriter interface.

func (*ResponseWriter) Write

func (w *ResponseWriter) Write(buf []byte) (int, error)

Write implements the dns.ResponseWriter interface.

func (*ResponseWriter) WriteMsg

func (w *ResponseWriter) WriteMsg(res *dns.Msg) error

WriteMsg implements the dns.ResponseWriter interface.