Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-10-27 08:14:18 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: updates some, remove others (#1187)

Browse Source 
Fix typo in kubernetes/README.md and remove DEV-README.md as it is stale
and information on the website is more up to date.

Remove large sections of text in plugin.md; just talk about how to
structure your plugin and docs.
This commit is contained in:
Miek Gieben
2017-10-31 13:33:41 +00:00
committed by John Belamaric
parent 1d4ac4adbb
commit fa2ae3fb43
3 changed files with 11 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
plugin.md
View File

@@ -2,35 +2,6 @@
## Writing Plugins ## Writing Plugins
From the Caddy docs:
> Oh yes, those pesky return values on ServeHTTP(). You read the documentation so you already know
> what they mean. But what does that imply for the behavior of your plugin?
>
> Basically, return a status code only if you did NOT write to the response body. If you DO write to
> the response body, return a status code of 0. Return an error value if your plugin encountered
> an error that you want logged. It is common to return an error status and an error value together,
> so that the error handler up the chain can write the correct error page.
>
> The returned status code is not logged directly; rather, it tells plugin higher up the chain
> what status code to use if/when the response body is written. Again, return a 0 status if you've
> already written a body!
In the DNS status codes are called rcodes and it's slightly harder to return the correct
answer in case of failure.
So CoreDNS treats:
* SERVFAIL (dns.RcodeServerFailure)
* REFUSED (dns.RcodeRefused)
* FORMERR (dns.RcodeFormatError)
* NOTIMP (dns.RcodeNotImplemented)
as special and will then assume nothing has written to the client. In all other cases it is assumes
something has been written to the client (by the plugin).
## Hooking It Up
See a couple of blog posts on how to write and add plugin to CoreDNS: See a couple of blog posts on how to write and add plugin to CoreDNS:
* <https://blog.coredns.io/2017/03/01/how-to-add-plugin-to-coredns/> * <https://blog.coredns.io/2017/03/01/how-to-add-plugin-to-coredns/>
@@ -39,14 +10,14 @@ See a couple of blog posts on how to write and add plugin to CoreDNS:
## Metrics ## Metrics
When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns"), and the When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns"), and the
*Subsystem* should be the name of the plugin. The README.md for the plugin should then *Subsystem* should be the name of the plugin. The README.md for the plugin should then also contain
also contain a *Metrics* section detailing the metrics. If the plugin supports dynamic health a *Metrics* section detailing the metrics. If the plugin supports dynamic health reporting it
reporting it should also have *Health* section detailing on its inner workings. should also have *Health* section detailing on some of its inner workings.
## Documentation ## Documentation
Each plugin should have a README.md explaining what the plugin does and how it is Each plugin should have a README.md explaining what the plugin does and how it is configured. The
configured. The file should have the following layout: file should have the following layout:
* Title: use the plugin's name * Title: use the plugin's name
* Subsection titled: "Syntax" * Subsection titled: "Syntax"
@@ -72,16 +43,17 @@ standard domain names created for this purpose.
## Fallthrough ## Fallthrough
In a perfect world the following would be true for plugin: "Either you are responsible for In a perfect world the following would be true for plugin: "Either you are responsible for a zone or
a zone or not". If the answer is "not", the plugin should call the next plugin in the chain. not". If the answer is "not", the plugin should call the next plugin in the chain. If "yes" it
If "yes" it should handle *all* names that fall in this zone and the names below - i.e. it should should handle *all* names that fall in this zone and the names below - i.e. it should handle the
handle the entire domain. entire domain.
~~~ txt ~~~ txt
. { . {
file example.org db.example file example.org db.example
} }
~~~ ~~~
In this example the *file* plugin is handling all names below (and including) `example.org`. If In this example the *file* plugin is handling all names below (and including) `example.org`. If
a query comes in that is not a subdomain (or equal to) `example.org` the next plugin is called. a query comes in that is not a subdomain (or equal to) `example.org` the next plugin is called.
@@ -96,44 +68,6 @@ reverse cases and **all other** request are handled by the backing plugin. This
"fallthrough" does. To keep things explicit we've opted that plugins implement such behavior "fallthrough" does. To keep things explicit we've opted that plugins implement such behavior
should implement a `fallthrough` keyword. should implement a `fallthrough` keyword.
### Example Fallthrough Usage
The following Corefile example, sets up the *reverse* plugin, but disables fallthrough. It
also defines a zonefile for use with the *file* plugin for other names in the `compute.internal`.
~~~ txt
arpa compute.internal {
reverse 10.32.0.0/16 {
hostname ip-{ip}.{zone[2]}
#fallthrough
}
file db.compute.internal compute.internal
}
~~~
This works for returning a response to a PTR request:
~~~ sh
% dig +nocmd @localhost +noall +ans -x 10.32.0.1
1.0.32.10.in-addr.arpa. 3600 IN PTR ip-10-32-0-1.compute.internal.
~~~
And for the forward:
~~~ sh
% dig +nocmd @localhost +noall +ans A ip-10-32-0-1.compute.internal
ip-10-32-0-1.compute.internal. 3600 IN A 10.32.0.1
~~~
But a query for `mx compute.internal` will return SERVFAIL. Now when we remove the '#' from
fallthrough and reload (on Unix: `kill -SIGUSR1 $(pidof coredns)`) CoreDNS, we *should* get an
answer for the MX query:
~~~ sh
% dig +nocmd @localhost +noall +ans MX compute.internal
compute.internal. 3600 IN MX 10 mx.compute.internal.
~~~
## Qualifying for main repo ## Qualifying for main repo
Plugins for CoreDNS can live out-of-tree, `plugin.cfg` defaults to CoreDNS' repo but other Plugins for CoreDNS can live out-of-tree, `plugin.cfg` defaults to CoreDNS' repo but other

43
plugin/kubernetes/DEV-README.md
View File

@@ -1,43 +0,0 @@
# Basic Setup for Development and Testing
## Launch Kubernetes
To run the tests, you'll need a private, live Kubernetes cluster. If you don't have one,
you can try out [minikube](https://github.com/kubernetes/minikube), which is
also available via Homebrew for OS X users.
## Configure Test Data
The test data is all in [this manifest](https://github.com/coredns/coredns/blob/master/.travis/kubernetes/dns-test.yaml)
and you can load it with `kubectl apply -f`. It will create a couple namespaces and some services.
For the tests to pass, you should not create anything else in the cluster.
## Proxy the API Server
Assuming your Kuberentes API server isn't running on http://localhost:8080, you will need to proxy from that
port to your cluster. You can do this with `kubectl proxy --port 8080`.
## Run CoreDNS Kubernetes Tests
Now you can run the tests locally, for example:
~~~
$ cd $GOPATH/src/github.com/coredns/coredns/test
$ go test -v -tags k8s
~~~
# Implementation Notes/Ideas
* Additional features:
* Implement IP selection and ordering (internal/external). Related to
wildcards and SkyDNS use of CNAMES.
* Expose arbitrary kubernetes repository data as TXT records?
* DNS Correctness
* Do we need to generate synthetic zone records for namespaces?
* Do we need to generate synthetic zone records for the skydns synthetic zones?
* Test cases
* Test with CoreDNS caching. CoreDNS caching for DNS response is working
using the `cache` directive. Tested working using 20s cache timeout
and A-record queries. Automate testing with cache in place.
* Automate CoreDNS performance tests. Initially for zone files, and for
pre-loaded k8s API cache. With and without CoreDNS response caching.

2
plugin/kubernetes/README.md
View File

@@ -38,7 +38,7 @@ kubernetes [ZONES...] {
``` ```
* `resyncperiod` specifies the Kubernetes data API **DURATION** period. * `resyncperiod` specifies the Kubernetes data API **DURATION** period.
* `endpoint` specifies the **URL** for a remove k8s API endpoint. * `endpoint` specifies the **URL** 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.
Multiple k8s API endpoints could be specified, separated by `,`s, e.g. Multiple k8s API endpoints could be specified, separated by `,`s, e.g.
`endpoint http://k8s-endpoint1:8080,http://k8s-endpoint2:8080`. CoreDNS `endpoint http://k8s-endpoint1:8080,http://k8s-endpoint2:8080`. CoreDNS