traefik

README

traefik

Name

traefik - returns records for hosts discovered in the routers of a Traefik instance.

Description

traefik polls a Traefik instance's API (/api/http/routers) and extracts the FQDNs from the Host() and HostSNI() matchers in each router's rule. For every discovered host it answers queries with either a CNAME pointing at the Traefik instance, or A/AAAA records for the Traefik instance's addresses. Records are refreshed periodically, so containers exposed through Traefik become resolvable without any manual DNS entries.

Queries for hosts that are not currently advertised by a Traefik router are answered with NXDOMAIN, or passed to the next plugin when fallthrough is set.

Motivation

Traefik already configures routes, services, and TLS from container labels, but the matching DNS records still have to be created by hand: a single address for Traefik and a CNAME to it per service. traefik removes that last manual step by polling the Traefik API and answering for the discovered host names on the fly. Paired with Traefik's label-based configuration, this automates DNS, TLS, and reverse proxying together when new containers are spun up.

Syntax

traefik [ENDPOINT] {
    cname CNAME
    a ADDRESS...
    aaaa ADDRESS...
    refreshinterval SECONDS
    ttl SECONDS
    retention SECONDS
    insecureskipverify [BOOL]
    resolveapihost [BOOL]
    filter FQDN...
    fallthrough [ZONES...]
}

• ENDPOINT the base URL of the Traefik API, without a trailing slash, for example https://traefik.example.org/api. The /api/http/routers endpoint is derived from it. Defaults to https://traefik.example.com/api.

Exactly one of cname, a, or aaaa is required; cname is mutually exclusive with a/aaaa.

• cname CNAME the fully qualified name (with or without a trailing .) returned as a CNAME for every discovered host, usually the host name of ENDPOINT.
• a ADDRESS... one or more IPv4 addresses of the Traefik instance, returned as A records for every discovered host.
• aaaa ADDRESS... one or more IPv6 addresses of the Traefik instance, returned as AAAA records for every discovered host.
• refreshinterval SECONDS how often the Traefik API is polled for changes, an integer number of seconds. Default 30.
• ttl SECONDS the TTL of the returned records, an integer number of seconds. Default 30.
• retention SECONDS how long a discovered host keeps being served after it disappears from Traefik (for example when its router or container label is removed), an integer number of seconds. The host is evicted on the first refresh after the window elapses; if it reappears within the window it is kept. Default 0, which evicts as soon as Traefik stops advertising the host.
• insecureskipverify [BOOL] skip TLS certificate verification when the API endpoint uses HTTPS with an untrusted certificate. The argument is optional; the bare directive means true. Default false.
• resolveapihost [BOOL] when set together with a/aaaa, also answer queries for the ENDPOINT host name itself with those addresses. The argument is optional; the bare directive means true. Default false.
• filter FQDN... only serve discovered hosts that are equal to, or a subdomain of, one of the given FQDNs; other hosts advertised by Traefik are ignored. Defaults to the server block's zone, so out-of-zone hosts are dropped unless you widen or narrow the filter. Each FQDN must itself be the server zone or a subdomain of it; when the server block has no zone (.) any FQDN is accepted.
• fallthrough [ZONES...] if a query for a host is not advertised by Traefik, pass it to the next plugin instead of returning NXDOMAIN. If ZONES is given, only queries in those zones fall through. See also the fallthrough section of the CoreDNS plugin documentation.

Examples

Return a CNAME to the Traefik instance for every host it advertises, polling every 30 seconds:

example.org:53 {
    hosts {
        10.0.0.2 traefik.example.org
        fallthrough
    }
    traefik https://traefik.example.org/api {
        cname traefik.example.org
        refreshinterval 30
        ttl 30
    }
    forward . 10.0.0.1
}

A container labelled with a Traefik router rule such as Host(`gitea.example.org`) is discovered on the next poll and resolves via the CNAME to traefik.example.org, which the hosts plugin answers with 10.0.0.2.

Return A records directly, and also resolve the API host name itself:

example.org:53 {
    traefik https://traefik.example.org/api {
        a 10.0.0.2
        resolveapihost
        ttl 30
    }
    forward . 10.0.0.1
}

Poll two Traefik instances from the same server block, each with its own records:

example.org:53 {
    traefik https://traefik-a.example.org/api {
        cname traefik-a.example.org
    }
    traefik https://traefik-b.example.org/api {
        a 10.0.0.3
    }
    forward . 10.0.0.1
}

Each block is polled independently; a query is answered by the first instance that knows the host.

Metrics

If monitoring is enabled (via the prometheus directive) the following metric is exported:

• coredns_traefik_request_count_total{server} - query count to the traefik plugin.

The server label indicates which server handled the request, see the metrics plugin for details.

Ready

This plugin reports readiness to the ready plugin. It becomes ready after the first successful refresh of data from the Traefik API.

Building

This plugin must be compiled into CoreDNS. Add it to plugin.cfg above the backend plugins that answer the zone — file, auto, secondary, etcd, and forward. CoreDNS runs plugins in plugin.cfg order, and those plugins answer authoritatively (or forward upstream) without falling through, so if any of them runs before traefik the query for a discovered host is answered (NXDOMAIN, or an upstream reply) before traefik ever sees it. Placing it just before file puts it ahead of the whole cluster:

traefik:github.com/scottt732/coredns-traefik

Then rebuild with go generate && go build, or make.

A plugin ordered before traefik (such as hosts) will handle matching queries first; give it fallthrough so unmatched names reach traefik (see the hosts example above).

Also See

See the manual and the Traefik API documentation.

Documentation

Index

• func ConvertIPsToString(ips []net.IP) string
• type HttpRouter
• type HttpRouterTls
• type HttpRouterTlsDomain
• type ITraefikClient
• type Traefik
  • func (t *Traefik) Name() string
  • func (t *Traefik) Ready() bool
  • func (t *Traefik) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type TraefikClient
  • func NewTraefikClient(cfg *TraefikConfig) (*TraefikClient, error)
  • func (c *TraefikClient) GetHttpRouters() (*[]HttpRouter, error)
• type TraefikConfig
• type TraefikConfigEntry
• type TraefikConfigEntryMap

Functions

func ConvertIPsToString

func ConvertIPsToString(ips []net.IP) string

Types

type HttpRouter

type HttpRouter struct {
	EntryPoints []string       `json:"entryPoints"`
	Service     string         `json:"service"`
	Rule        string         `json:"rule"`
	Priority    int            `json:"priority"`
	Tls         *HttpRouterTls `json:"tls,omitempty"`
	Status      string         `json:"status"`
	Using       []string       `json:"using"`
	Name        string         `json:"name"`
	Provider    string         `json:"provider"`
}

type HttpRouterTls

type HttpRouterTls struct {
	Options string                `json:"options"`
	Domains []HttpRouterTlsDomain `json:"domains"`
}

type HttpRouterTlsDomain

type HttpRouterTlsDomain struct {
	Main string   `json:"main"`
	Sans []string `json:"sans"`
}

type ITraefikClient

type ITraefikClient interface {
	GetHttpRouters() (*[]HttpRouter, error)
}

type Traefik

type Traefik struct {
	Next      plugin.Handler
	Instances []*traefikInstance
	Fall      fall.F
}

func (*Traefik) Name

func (t *Traefik) Name() string

func (*Traefik) Ready

func (t *Traefik) Ready() bool

Ready reports readiness to the ready plugin. The plugin is ready once every configured Traefik instance has completed its first refresh.

func (*Traefik) ServeDNS

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

type TraefikClient

type TraefikClient struct {
	ITraefikClient
	// contains filtered or unexported fields
}

func NewTraefikClient

func NewTraefikClient(cfg *TraefikConfig) (*TraefikClient, error)

func (*TraefikClient) GetHttpRouters

func (c *TraefikClient) GetHttpRouters() (*[]HttpRouter, error)

type TraefikConfig

type TraefikConfig struct {
	// contains filtered or unexported fields
}

type TraefikConfigEntry

type TraefikConfigEntry struct {
	// contains filtered or unexported fields
}

type TraefikConfigEntryMap

type TraefikConfigEntryMap map[string]*TraefikConfigEntry