mirror of
https://github.com/coredns/coredns.git
synced 2026-10-25 11:45:43 -04:00
c2acad2866
The README and man page introduce the apex with "By default the apex of the zone will look like the following", but the SOA fields shown do not match what soa() actually emits. plugin/k8s_external/apex.go sets Refresh 7200, Retry 1800, Expire 86400 and Minttl e.ttl (default 5 seconds), while the example listed 14400/3600/604800 and annotated the minimum value of 5 as "4 hours". Align the example with the emitted values and fix the minimum's unit. Signed-off-by: Vincent <1729065730@qq.com>
196 lines
3.9 KiB
Groff
196 lines
3.9 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-K8S_EXTERNAL" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIk8s_external\fP - resolves load balancer, external IPs from outside Kubernetes clusters and if enabled headless services.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
This plugin allows an additional zone to resolve the external IP address(es) of a Kubernetes
|
|
service and headless services. This plugin is only useful if the \fIkubernetes\fP plugin is also loaded.
|
|
|
|
.PP
|
|
The plugin uses an external zone to resolve in-cluster IP addresses. It only handles queries for A,
|
|
AAAA, SRV, and PTR records; To make it a proper DNS zone, it handles SOA and NS queries for the apex of the zone.
|
|
|
|
.PP
|
|
By default the apex of the zone will look like the following (assuming the zone used is \fB\fCexample.org\fR):
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
example.org. 5 IN SOA ns1.dns.example.org. hostmaster.example.org. (
|
|
12345 ; serial
|
|
7200 ; refresh (2 hours)
|
|
1800 ; retry (30 minutes)
|
|
86400 ; expire (1 day)
|
|
5 ; minimum (5 seconds)
|
|
)
|
|
example.org 5 IN NS ns1.dns.example.org.
|
|
|
|
ns1.dns.example.org. 5 IN A ....
|
|
ns1.dns.example.org. 5 IN AAAA ....
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Note that we use the \fB\fCdns\fR subdomain for the records DNS needs (see the \fB\fCapex\fR directive). Also
|
|
note the SOA's serial number is static. The IP addresses of the nameserver records are those of the
|
|
CoreDNS service.
|
|
|
|
.PP
|
|
The \fIk8s_external\fP plugin handles the subdomain \fB\fCdns\fR and the apex of the zone itself; all other
|
|
queries are resolved to addresses in the cluster.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
k8s\_external [ZONE...]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBZONES\fP zones \fIk8s_external\fP should be authoritative for.
|
|
|
|
|
|
.PP
|
|
If you want to change the apex domain or use a different TTL for the returned records you can use
|
|
this extended syntax.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
k8s\_external [ZONE...] {
|
|
apex APEX
|
|
ttl TTL
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBAPEX\fP is the name (DNS label) to use for the apex records; it defaults to \fB\fCdns\fR.
|
|
.IP \(bu 4
|
|
\fB\fCttl\fR allows you to set a custom \fBTTL\fP for responses. The default is 5 (seconds).
|
|
|
|
|
|
.PP
|
|
If you want to enable headless service resolution, you can do so by adding \fB\fCheadless\fR option.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
k8s\_external [ZONE...] {
|
|
headless
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
if there is a headless service with external IPs set, external IPs will be resolved
|
|
|
|
|
|
.PP
|
|
If the queried domain does not exist, you can fall through to next plugin by adding the \fB\fCfallthrough\fR option.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
k8s\_external [ZONE...] {
|
|
fallthrough [ZONE...]
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Enable names under \fB\fCexample.org\fR to be resolved to in-cluster DNS addresses.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
kubernetes cluster.local
|
|
k8s\_external example.org
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
With the Corefile above, the following Service will get an \fB\fCA\fR record for \fB\fCtest.default.example.org\fR with the IP address \fB\fC192.168.200.123\fR.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
apiVersion: v1
|
|
kind: Service
|
|
metadata:
|
|
name: test
|
|
namespace: default
|
|
spec:
|
|
clusterIP: None
|
|
externalIPs:
|
|
\- 192.168.200.123
|
|
type: ClusterIP
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
The \fIk8s_external\fP plugin can be used in conjunction with the \fItransfer\fP plugin to enable
|
|
zone transfers. Notifies are not supported.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
. {
|
|
transfer example.org {
|
|
to *
|
|
}
|
|
kubernetes cluster.local
|
|
k8s\_external example.org
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
With the \fB\fCfallthrough\fR option, if the queried domain does not exist, it will be passed to the next plugin that matches the zone.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
kubernetes cluster.local
|
|
k8s\_external example.org {
|
|
fallthrough
|
|
}
|
|
forward . 8.8.8.8
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
For some background see resolve external IP address
|
|
\[la]https://github.com/kubernetes/dns/issues/242\[ra].
|
|
And A records for services with Load Balancer IP
|
|
\[la]https://github.com/coredns/coredns/issues/1851\[ra].
|
|
|