45 lines
1.4 KiB
Markdown
45 lines
1.4 KiB
Markdown
# dns-sync plugin template
|
|
|
|
This directory is a documentation/example package. dns-sync does not load it
|
|
from this location.
|
|
|
|
Copy it to one of these locations and rename it for the application:
|
|
|
|
dns_sync/plugins/adapters/<plugin_name>/
|
|
|
|
for a built-in plugin, or:
|
|
|
|
$DNS_SYNC_PLUGIN_PATH/<plugin_name>/
|
|
|
|
for an external plugin.
|
|
|
|
The canonical package layout is:
|
|
|
|
<plugin_name>/
|
|
├── __init__.py
|
|
└── client.py
|
|
|
|
`__init__.py` is the dns-sync adapter boundary. It owns endpoint discovery,
|
|
generic capabilities, native-to-normalized translation, apply, verify, and
|
|
optional retirement behavior.
|
|
|
|
`client.py` is private to the plugin. It owns authentication, transport,
|
|
application-specific models, native request/response handling, and endpoint
|
|
operations.
|
|
|
|
## Before enabling a copied plugin
|
|
|
|
1. Rename `example`, `ExampleClient`, and `ExampleRecord`.
|
|
2. Implement `configured_endpoints(config)`.
|
|
3. Implement the native client methods.
|
|
4. Declare only capabilities the plugin really supports.
|
|
5. Implement discovery for those object types.
|
|
6. Translate normalized desired state into native state in `apply()`.
|
|
7. Re-discover mutations and return the real endpoint-local key.
|
|
8. Implement `verify()`.
|
|
9. Add `retire()` only when retirement/deletion is safely supported.
|
|
10. Add focused adapter/client tests.
|
|
11. Validate using read-only reconciliation before enabling mutations.
|
|
|
|
See the root `README.md` for the complete plugin contract and architecture.
|