Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2026-04-12 06:55:33 -04:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): regenerate man pages (#7971)

Browse Source
This commit is contained in:
Ville Vesilehto
2026-03-27 05:35:09 +02:00
committed by GitHub
parent 49b18b8af6
commit 0132ad86b5
60 changed files with 2110 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
man/coredns-kubernetes.7
View File

@@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-KUBERNETES" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
.TH "COREDNS-KUBERNETES" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@@ -50,6 +50,9 @@ kubernetes [ZONES...] {
endpoint URL
tls CERT KEY CACERT
kubeconfig KUBECONFIG [CONTEXT]
apiserver\_qps QPS
apiserver\_burst BURST
apiserver\_max\_inflight MAX
namespaces NAMESPACE...
labels EXPRESSION
pods POD\-MODE
@@ -58,6 +61,8 @@ kubernetes [ZONES...] {
noendpoints
fallthrough [ZONES...]
ignore empty\_service
multicluster [ZONES...]
startup\_timeout DURATION
}
.fi
@@ -65,7 +70,8 @@ kubernetes [ZONES...] {
.IP \(bu 4
\fB\fCendpoint\fR specifies the \fBURL\fP for a remote k8s API endpoint.
If omitted, it will connect to k8s in-cluster using the cluster service account.
If omitted, it will connect to k8s in-cluster using the cluster service account. Needs \fB\fCtls\fR for clusters with authentication.
This option is ignored if \fB\fCkubeconfig\fR is set.
.IP \(bu 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCACERT\fP are the TLS cert, key and the CA cert file names for remote k8s connection.
This option is ignored if connecting in-cluster (i.e. endpoint is not specified).
@@ -73,7 +79,16 @@ This option is ignored if connecting in-cluster (i.e. endpoint is not specified)
\fB\fCkubeconfig\fR \fBKUBECONFIG [CONTEXT]\fP authenticates the connection to a remote k8s cluster using a kubeconfig file.
\fB[CONTEXT]\fP is optional, if not set, then the current context specified in kubeconfig will be used.
It supports TLS, username and password, or token-based authentication.
This option is ignored if connecting in-cluster (i.e., the endpoint is not specified).
This option is ignored if omitted. The cluster address in the \fB\fCkubeconfig\fR is given preference.
.IP \(bu 4
\fB\fCapiserver_qps\fR \fBQPS\fP sets the maximum queries per second (QPS) rate limit for requests.
This allows you to control the rate at which the plugin sends requests to the API server to prevent overwhelming it.
.IP \(bu 4
\fB\fCapiserver_burst\fR \fBBURST\fP sets the maximum burst size for requests.
This allows temporary spikes in request rate up to this value, even if it exceeds the QPS limit.
.IP \(bu 4
\fB\fCapiserver_max_inflight\fR \fBMAX\fP sets the maximum number of concurrent in-flight requests.
This caps the total number of simultaneous requests the plugin can make to the API server.
.IP \(bu 4
\fB\fCnamespaces\fR \fBNAMESPACE [NAMESPACE...]\fP only exposes the k8s namespaces listed.
If this option is omitted all namespaces are exposed
@@ -120,7 +135,7 @@ IP address (e.g., \fB\fC1-2-3-4.my-service.namespace.svc.cluster.local.\fR)
If this directive is included, then name selection for endpoints changes as
follows: Use the hostname of the endpoint, or if hostname is not set, use the
pod name of the pod targeted by the endpoint. If there is no pod targeted by
the endpoint, use the dashed IP address form.
the endpoint or pod name is longer than 63, use the dashed IP address form.
.IP \(bu 4
\fB\fCttl\fR allows you to set a custom TTL for responses. The default is 5 seconds. The minimum TTL allowed is
0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.
@@ -138,16 +153,41 @@ queries for those zones will be subject to fallthrough.
\fB\fCignore empty_service\fR returns NXDOMAIN for services without any ready endpoint addresses (e.g., ready pods).
This allows the querying pod to continue searching for the service in the search path.
The search path could, for example, include another Kubernetes cluster.
.IP \(bu 4
\fB\fCmulticluster\fR defines the multicluster zones as defined by Multi-Cluster
Services API (MCS-API). Specifying this option is generally paired with the
installation of an MCS-API implementation and the ServiceImport and ServiceExport
CRDs. The plugin MUST be authoritative for the zones listed here.
.IP \(bu 4
\fB\fCstartup_timeout\fR specifies the \fBDURATION\fP value that limits the time to wait for informer cache synced
when the kubernetes plugin starts. If not specified, the default timeout will be 5s.
.PP
Enabling zone transfer is done by using the \fItransfer\fP plugin.
.SH "STARTUP"
.PP
When CoreDNS starts with the \fIkubernetes\fP plugin enabled, it will delay serving DNS for up to 5 seconds
until it can connect to the Kubernetes API and synchronize all object watches. If this cannot happen within
5 seconds, then CoreDNS will start serving DNS while the \fIkubernetes\fP plugin continues to try to connect
and synchronize all object watches. CoreDNS will answer SERVFAIL to any request made for a Kubernetes record
that has not yet been synchronized. You can also determine how long to wait by specifying \fB\fCstartup_timeout\fR.
.SH "MONITORING KUBERNETES ENDPOINTS"
.PP
The \fIkubernetes\fP plugin watches Endpoints via the \fB\fCdiscovery.EndpointSlices\fR API.
.SH "READY"
.PP
This plugin reports readiness to the ready plugin. This will happen after it has synced to the
Kubernetes API.
.SH "PTR RECORDS"
.PP
This plugin creates PTR records for every Pod selected by a Service. If a given Pod is selected by more than
one Service a separate PTR record will exist for each Service selecting it.
.SH "EXAMPLES"
.PP
Handle all queries in the \fB\fCcluster.local\fR zone. Connect to Kubernetes in-cluster. Also handle all
@@ -196,6 +236,20 @@ kubernetes cluster.local {
.fi
.RE
.PP
Configure multicluster
.PP
.RS
.nf
kubernetes cluster.local clusterset.local {
multicluster clusterset.local
}
.fi
.RE
.SH "STUBDOMAINS AND UPSTREAMNAMESERVERS"
.PP
Here we use the \fIforward\fP plugin to implement a stubDomain that forwards \fB\fCexample.local\fR to the nameserver \fB\fC10.100.0.10:53\fR.
@@ -256,37 +310,6 @@ cluster.local {
.fi
.RE
.SH "WILDCARDS"
.PP
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:
.IP \(bu 4
\fIendpoint\fP in an \fB\fCA\fR record request: \fIendpoint\fP.service.namespace.svc.zone, e.g., \fB\fC*.nginx.ns.svc.cluster.local\fR
.IP \(bu 4
\fIservice\fP in an \fB\fCA\fR record request: \fIservice\fP.namespace.svc.zone, e.g., \fB\fC*.ns.svc.cluster.local\fR
.IP \(bu 4
\fInamespace\fP in an \fB\fCA\fR record request: service.\fInamespace\fP.svc.zone, e.g., \fB\fCnginx.*.svc.cluster.local\fR
.IP \(bu 4
\fIport and/or protocol\fP in an \fB\fCSRV\fR request: \fBport_.\fPprotocol_.service.namespace.svc.zone.,
e.g., \fB\fC_http.*.service.ns.svc.cluster.local\fR
.IP \(bu 4
multiple wildcards are allowed in a single query, e.g., \fB\fCA\fR Request \fB\fC*.*.svc.zone.\fR or \fB\fCSRV\fR request \fB\fC*.*.*.*.svc.zone.\fR
.PP
For example, wildcards can be used to resolve all Endpoints for a Service as \fB\fCA\fR records. e.g.: \fB\fC*.service.ns.svc.myzone.local\fR will return the Endpoint IPs in the Service \fB\fCservice\fR in namespace \fB\fCdefault\fR:
.PP
.RS
.nf
*.service.default.svc.cluster.local. 5 IN A 192.168.10.10
*.service.default.svc.cluster.local. 5 IN A 192.168.25.15
.fi
.RE
.SH "METADATA"
.PP
The kubernetes plugin will publish the following metadata, if the \fImetadata\fP
@@ -308,11 +331,14 @@ plugin is also enabled:
\fB\fCkubernetes/client-namespace\fR: the client pod's namespace (see requirements below)
.IP \(bu 4
\fB\fCkubernetes/client-pod-name\fR: the client pod's name (see requirements below)
.IP \(bu 4
\fB\fCkubernetes/client-label/<label key>\fR: a label on the client pod (see requirements below)
.PP
The \fB\fCkubernetes/client-namespace\fR and \fB\fCkubernetes/client-pod-name\fR metadata work by reconciling the
client IP address in the DNS request packet to a known pod IP address. Therefore the following is required:
The \fB\fCkubernetes/client-namespace\fR, \fB\fCkubernetes/client-pod-name\fR, and \fB\fCkubernetes/client-label/<label key>\fR
metadata work by reconciling the client IP address in the DNS request packet to a known pod IP address.
Therefore the following is required:
* \fB\fCpods verified\fR mode must be enabled
* the remote IP address in the DNS packet received by CoreDNS must be the IP address
of the Pod that sent the request.
@@ -341,9 +367,16 @@ It may take one of the three values:
.RE
.PP
The following are client level metrics to monitor apiserver request latency & status codes. \fB\fCverb\fR identifies the apiserver request type
\[la]https://kubernetes.io/docs/reference/using-api/api-concepts/#single-resource-api\[ra] and \fB\fChost\fR denotes the apiserver endpoint.
* \fB\fCcoredns_kubernetes_rest_client_request_duration_seconds{verb, host}\fR - captures apiserver request latency perceived by client grouped by \fB\fCverb\fR and \fB\fChost\fR.
* \fB\fCcoredns_kubernetes_rest_client_rate_limiter_duration_seconds{verb, host}\fR - captures apiserver request latency contributed by client side rate limiter grouped by \fB\fCverb\fR & \fB\fChost\fR.
* \fB\fCcoredns_kubernetes_rest_client_requests_total{method, code, host}\fR - captures total apiserver requests grouped by \fB\fCmethod\fR, \fB\fCstatus_code\fR & \fB\fChost\fR.
.SH "BUGS"
.PP
The duration metric only supports the "headless_with_selector" service currently.
The duration metric does not yet support the \fB\fCheadless_without_selector\fR service kind.
.SH "SEE ALSO"
.PP