Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-10-28 00:34:24 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: plugin.md (#2813)

Browse Source 
Update this file, give Readiness its own section and remove the talk
about the *reverse* plugin as it does not exist in the main tree
anymore.

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
2019-05-05 17:51:51 +01:00
committed by Yong Tang
parent 076b8d4fba
commit 0c2dbed82a
1 changed files with 8 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
plugin.md
View File

@@ -59,8 +59,10 @@ When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns")
*Subsystem* should be the name of the plugin. The README.md for the plugin should then also contain *Subsystem* should be the name of the plugin. The README.md for the plugin should then also contain
a *Metrics* section detailing the metrics. a *Metrics* section detailing the metrics.
## Readiness
If the plugin supports signalling readiness it should have a *Ready* section detailing how it If the plugin supports signalling readiness it should have a *Ready* section detailing how it
works. works, and implement the `ready.Readiness` interface.
## Documentation ## Documentation
@@ -108,21 +110,14 @@ entire domain and all sub domains.
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.
Now, the world isn't perfect, and there are good reasons to "fallthrough" to the next middleware, Now, the world isn't perfect, and there are may be reasons to "fallthrough" to the next plugin,
meaning a plugin is only responsible for a *subset* of names within the zone. The first of these meaning a plugin is only responsible for a *subset* of names within the zone.
to appear was the *reverse* plugin that synthesis PTR and A/AAAA responses (useful with IPv6).
The nature of the *reverse* plugin is such that it only deals with A,AAAA and PTR and then only
for a subset of the names. Ideally you would want to layer *reverse* **in front off** another
plugin such as *file* or *auto* (or even *forward*). This means *reverse* handles some special
reverse cases and **all other** request are handled by the backing plugin. This is exactly what
"fallthrough" does. To keep things explicit we've opted that plugins implement such behavior
should implement a `fallthrough` keyword.
The `fallthrough` directive should optionally accept a list of zones. Only queries for records The `fallthrough` directive should optionally accept a list of zones. Only queries for records
in one of those zones should be allowed to fallthrough. in one of those zones should be allowed to fallthrough. See `plugin/pkg/fallthrough` for the
implementation.
## 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
repos work just as well. So when do we consider the inclusion of a new plugin in the main repo? repos work just as well. So when do we consider the inclusion of a new plugin in the main repo?