kubernetes

README

kubernetes

kubernetes enables reading zone data from a kubernetes cluster. It implements the spec defined for kubernetes DNS-Based service discovery:

Service A records are constructed as "myservice.mynamespace.svc.coredns.local" where:

• "myservice" is the name of the k8s service
• "mynamespace" is the k8s namespace for the service, and
• "svc" indicates this is a service
• "coredns.local" is the zone

Pod A records are constructed as "1-2-3-4.mynamespace.pod.coredns.local" where:

• "1-2-3-4" is derived from the ip address of the pod (1.2.3.4 in this example)
• "mynamespace" is the k8s namespace for the service, and
• "pod" indicates this is a pod
• "coredns.local" is the zone

Endpoint A records are constructed as "epname.myservice.mynamespace.svc.coredns.local" where:

• "epname" is the hostname (or name constructed from IP) of the endpoint
• "myservice" is the name of the k8s service that the endpoint serves
• "mynamespace" is the k8s namespace for the service, and
• "svc" indicates this is a service
• "coredns.local" is the zone

Also supported are PTR and SRV records for services/endpoints.

Syntax

This is an example kubernetes configuration block, with all options described:

# kubernetes <zone> [<zone>] ...
#
# Use kubernetes middleware for domain "coredns.local"
# Reverse domain zones can be defined here (e.g. 0.0.10.in-addr.arpa),
# or instead with the "cidrs" option.
#
kubernetes coredns.local {

	# resyncperiod <period>
	#
	# Kubernetes data API resync period. Default is 5m
	# Example values: 60s, 5m, 1h
	#
	resyncperiod 5m

	# endpoint <url>
	#
	# Use url for a remote k8s API endpoint.  If omitted, it will connect to
	# k8s in-cluster using the cluster service account.
	#
	endpoint https://k8s-endpoint:8080

	# tls <cert-filename> <key-filename> <cacert-filename>
	#
	# The tls cert, key and the CA cert filenanames for remote k8s connection.
	# This option is ignored if connecting in-cluster (i.e. endpoint is not
	# specified).
	#
	tls cert key cacert

	# namespaces <namespace> [<namespace>] ...
	#
	# Only expose the k8s namespaces listed.  If this option is omitted
	# all namespaces are exposed
	#
	namespaces demo

	# lables <expression> [,<expression>] ...
	#
	# Only expose the records for kubernetes objects
	# that match this label selector. The label
	# selector syntax is described in the kubernetes
	# API documentation: http://kubernetes.io/docs/user-guide/labels/
	# Example selector below only exposes objects tagged as
	# "application=nginx" in the staging or qa environments.
	#
	labels environment in (staging, qa),application=nginx

	# pods <disabled|insecure|verified>
	#
	# Set the mode of responding to pod A record requests.
	# e.g 1-2-3-4.ns.pod.zone.  This option is provided to allow use of
	# SSL certs when connecting directly to pods.
	# Valid values: disabled, verified, insecure
	#  disabled: Do not process pod requests, always returning NXDOMAIN
	#  insecure: Always return an A record with IP from request (without
	#            checking k8s).  This option is is vulnerable to abuse if
	#            used maliciously in conjuction with wildcard SSL certs.
	#  verified: Return an A record if there exists a pod in same
	#            namespace with matching IP.  This option requires
	#            substantially more memory than in insecure mode, since it
	#            will maintain a watch on all pods.
	# Default value is "disabled".
	#
	pods disabled

	# cidrs <cidr> [<cidr>] ...
	#
	# Expose cidr ranges to reverse lookups.  Include any number of space
	# delimited cidrs, and or multiple cidrs options on separate lines.
	# kubernetes middleware will respond to PTR requests for ip addresses
	# that fall within these ranges.
	#
	cidrs 10.0.0.0/24 10.0.10.0/25

	# upstream <address> [<address>] ...
	#
	# Defines upstream resolvers used for resolving services that point to
	# external hosts (External Services).  <address> can be an ip, an ip:port, or
	# a path to a file structured like resolv.conf.
	upstream 12.34.56.78:53
	
	# fallthrough
	#
	# If a query for a record in the cluster zone results in NXDOMAIN,
	# normally that is what the response will be. However, if you specify
	# this option, the query will instead be passed on down the middleware
	# chain, which can include another middleware to handle the query.
	fallthrough
}

Wildcards

Some query labels accept a wildcard value to match any value. If a label is a valid wildcard (*, or the word "any"), then that label will match all values. The labels that accept wildcards are:

• service in an A record request: service.namespace.svc.zone.
  • e.g. *.ns.svc.myzone.local
• namespace in an A record request: service.namespace.svc.zone.
  • e.g. nginx.*.svc.myzone.local
• port and/or protocol in an SRV request: _port._protocol.service.namespace.svc.zone.
  • e.g. _http.*.service.ns.svc.
• multiple wild cards are allowed in a single query.
  • e.g. A Request *.*.svc.zone. or SRV request *.*.*.*.svc.zone.

Deployment in Kubernetes

See the deployment repository for details on how to deploy CoreDNS in Kubernetes.

Documentation

Overview

Package kubernetes provides the kubernetes backend.

Index

• Constants
• func NormalizeZoneList(zones []string) []string
• type Kubernetes
  • func (k *Kubernetes) Debug() string
  • func (k *Kubernetes) InitKubeCache() (err error)
  • func (k *Kubernetes) IsNameError(err error) bool
  • func (k *Kubernetes) Lookup(state request.Request, name string, typ uint16) (*dns.Msg, error)
  • func (k Kubernetes) Name() string
  • func (k Kubernetes) PTR(zone string, state request.Request) ([]dns.RR, error)
  • func (k *Kubernetes) PrimaryZone() string
  • func (k *Kubernetes) Records(r recordRequest) ([]msg.Service, error)
  • func (k *Kubernetes) Reverse(state request.Request, exact bool, opt middleware.Options) ([]msg.Service, []msg.Service, error)
  • func (k Kubernetes) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (k *Kubernetes) Services(state request.Request, exact bool, opt middleware.Options) (svcs []msg.Service, debug []msg.Service, err error)

Constants

const (
	// PodModeDisabled is the default value where pod requests are ignored
	PodModeDisabled = "disabled"
	// PodModeVerified is where Pod requests are answered only if they exist
	PodModeVerified = "verified"
	// PodModeInsecure is where pod requests are answered without verfying they exist
	PodModeInsecure = "insecure"
	// DNSSchemaVersion is the schema version: https://github.com/kubernetes/dns/blob/master/docs/specification.md
	DNSSchemaVersion = "1.0.1"
)

Functions

func NormalizeZoneList

func NormalizeZoneList(zones []string) []string

NormalizeZoneList filters the zones argument to remove array items that conflict with other items in zones. For example, providing the following zones array:

[ "a.b.c", "b.c", "a", "e.d.f", "a.b" ]

Returns:

[ "a.b.c", "a", "e.d.f", "a.b" ]

Zones filted out:

• "b.c" because "a.b.c" and "b.c" share the common top level "b.c". First listed zone wins if there is a conflict.

Note: This may prove to be too restrictive in practice.

Need to find counter-example use-cases.

Types

type Kubernetes

type Kubernetes struct {
	Next  middleware.Handler
	Zones []string

	Proxy         proxy.Proxy // Proxy for looking up names during the resolution process
	APIEndpoint   string
	APICertAuth   string
	APIClientCert string
	APIClientKey  string
	APIConn       dnsController
	ResyncPeriod  time.Duration
	Namespaces    []string
	LabelSelector *unversionedapi.LabelSelector
	Selector      *labels.Selector
	PodMode       string
	ReverseCidrs  []net.IPNet
	Fallthrough   bool
	// contains filtered or unexported fields
}

Kubernetes implements a middleware that connects to a Kubernetes cluster.

func (*Kubernetes) Debug

func (k *Kubernetes) Debug() string

Debug implements the ServiceBackend interface.

func (*Kubernetes) InitKubeCache

func (k *Kubernetes) InitKubeCache() (err error)

InitKubeCache initializes a new Kubernetes cache.

func (*Kubernetes) IsNameError

func (k *Kubernetes) IsNameError(err error) bool

IsNameError implements the ServiceBackend interface.

func (*Kubernetes) Lookup

func (k *Kubernetes) Lookup(state request.Request, name string, typ uint16) (*dns.Msg, error)

Lookup implements the ServiceBackend interface.

func (Kubernetes) Name

func (k Kubernetes) Name() string

Name implements the Handler interface.

func (Kubernetes) PTR

func (k Kubernetes) PTR(zone string, state request.Request) ([]dns.RR, error)

PTR Record returns PTR records from kubernetes.

func (*Kubernetes) PrimaryZone

func (k *Kubernetes) PrimaryZone() string

PrimaryZone will return the first non-reverse zone being handled by this middleware

func (*Kubernetes) Records

func (k *Kubernetes) Records(r recordRequest) ([]msg.Service, error)

Records looks up services in kubernetes. If exact is true, it will lookup just this name. This is used when find matches when completing SRV lookups for instance.

func (*Kubernetes) Reverse

func (k *Kubernetes) Reverse(state request.Request, exact bool, opt middleware.Options) ([]msg.Service, []msg.Service, error)

Reverse implements the ServiceBackend interface.

func (Kubernetes) ServeDNS

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

ServeDNS implements the middleware.Handler interface.

func (*Kubernetes) Services

func (k *Kubernetes) Services(state request.Request, exact bool, opt middleware.Options) (svcs []msg.Service, debug []msg.Service, err error)

Services implements the ServiceBackend interface.