StackExchange/dnscontrol
1
1
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2025-10-04 02:45:35 +08:00
Code Issues Projects Releases Packages Wiki Activity

Update writing-providers.md (#172)

Browse source 
* Update writing-providers.md
This commit is contained in:
Tom Limoncelli 2017-08-04 12:19:10 -07:00 • committed by GitHub
parent b5e4ab1e23
commit f214fb4515
1 changed files with 134 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

157
docs/writing-providers.md
View file

@ -4,40 +4,151 @@ layout: default
# Writing new DNS providers
Writing a new DNS provider is a relatively straightforward process. You essentially need to implement the [providers.DNSServiceProvider interface.](https://godoc.org/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider) and the system takes care of the rest.
Writing a new DNS provider is a relatively straightforward process.
You essentially need to implement the
[providers.DNSServiceProvider interface.](https://godoc.org/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider)
and the system takes care of the rest.
Use another provider as the basis for yours. Pick the provider that has the most similar
API. Some APIs update one DNS record at a time (cloudflare, namedotcom, activedir), some APIs update
all the DNS records on a particular label, some APIs require you to upload the entire
zone every time (bind, gandi).
You'll notice that most providers use the "diff" module to detect differences. It takes
two zones and returns records that are unchanged, created, deleted, and modified. Even
if the API simply requires the entire zone to be uploaded each time, we prefer to list
the specific changes so the user knows exactly what changed.
## Step 1: General advice
Here are some tips:
A provider can be a DnsProvider, a Registrar, or both. We recommend
you write the DnsProvider first, release it, and then write the
Registrar if needed.
* A provider can be a DnsProvider, a Registrar, or both. We recommend you write the DnsProvider first, release it, and then write the Registrar if needed.
* Create a directory for the provider called `providers/name` where `name` is all lowercase and represents the commonly-used name for the service.
* The main driver should be called `providers/name/nameProvider.go`. The API abstraction is usually in a separate file (often called `api.go`).
* List the provider in `providers/_all/all.go` so DNSControl knows it exists.
* Implement all the calls in [providers.DNSServiceProvider interface.](https://godoc.org/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider). The function `GetDomainCorrections` is a bit interesting. It returns a list of corrections to be made. These are in the form of functions that DNSControl can call to actually make the corrections.
* If you have any questions, please dicuss them in the Github issue related to the request for this provider. Please let us know what was confusing so we can update this document with advice for future authors (or feel free to update [this document](https://github.com/StackExchange/dnscontrol/blob/master/docs/writing-providers.md) yourself!).
* Add the provider to the provider list: [docs/provider-list.html](https://github.com/StackExchange/dnscontrol/blob/master/docs/provider-list.html).
* Add the provider to the README: [README.md](https://github.com/StackExchange/dnscontrol)
If you have any questions, please dicuss them in the Github issue
related to the request for this provider. Please let us know what
was confusing so we can update this document with advice for future
authors (or even better, update [this
document](https://github.com/StackExchange/dnscontrol/blob/master/docs/writing-providers.md)
yourself.)
## Documentation
Please add a page to the docs folder for your provider, and add it to the list in the main project readme.
## Step 2: Pick a base provider
Pick a similar provider as your base. Providers basically fall
into three general categories:
* **zone:** The API requires you to upload the entire zone every time. (BIND, GANDI).
* **incremental-record:** The API lets you add/change/delete individual DNS records. (ACTIVEDIR, CLOUDFLARE, NAMEDOTCOM, GCLOUD, ROUTE53)
* **incremental-label:** Similar to incremental, but the API requires you to update all the records related to a particular label each time. For example, if a label (www.example.com) has an A and MX record, any change requires replacing all the records for that label.
TODO: Categorize DNSIMPLE, NAMECHEAP
All providers use the "diff" module to detect differences. It takes
two zones and returns records that are unchanged, created, deleted,
and modified. The incremental providers use the differences to
update individual records or recordsets. The zone providers use the
information to print a human-readable list of what is being changed,
but upload the entire new zone.
## Step 3: Create the driver skeleton
Create a directory for the provider called `providers/name` where
`name` is all lowercase and represents the commonly-used name for
the service.
The main driver should be called `providers/name/nameProvider.go`.
The API abstraction is usually in a separate file (often called
`api.go`).
## Step 4: Activate the driver
Edit
[providers/_all/all.go](https://github.com/StackExchange/dnscontrol/blob/master/providers/_all/all.go).
Add the provider list so DNSControl knows it exists.
## Step 5: Implement
Implement all the calls in
[providers.DNSServiceProvider interface.](https://godoc.org/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider).
The function `GetDomainCorrections` is a bit interesting. It returns
a list of corrections to be made. These are in the form of functions
that DNSControl can call to actually make the corrections.
## Step 6: Unit Test
Make sure the existing unit tests work. Add unit tests for any
complex algorithms in the new code.
Run the unit tests with this command:
cd dnscontrol
go test ./...
## Step 7: Integration Test
This is the most important kind of testing when adding a new provider.
Integration tests use a test account and a real domain.
* Edit [integrationTest/providers.json](https://github.com/StackExchange/dnscontrol/blob/master/integrationTest/providers.json): Add the creds.json info required for this provider.
For example, this will run the tests using BIND:
```
cd dnscontrol/integrationTest
go test -v -verbose -provider BIND
```
(BIND is a good place to start since it doesn't require any API keys.)
This will run the tests on Amazon AWS Route53:
```
export R53_DOMAIN=dnscontroltest-r53.com # Use a test domain.
export R53_KEY_ID=CHANGE_TO_THE_ID
export R53_KEY='CHANGE_TO_THE_KEY'
go test -v -verbose -provider ROUTE53
```
## Step 5: Update docs
* Edit [README.md](https://github.com/StackExchange/dnscontrol): Add the provider to the bullet list.
* Edit [docs/provider-list.html](https://github.com/StackExchange/dnscontrol/blob/master/docs/provider-list.html): Add the provider to the provider list.
* Create `docs/_providers/PROVIDERNAME.md`: Use one of the other files in that directory as a base.
## Step 6: Submit a PR
At this point you can submit a PR.
Actually you can submit the PR even earlier if you just want feedback,
input, or have questions. This is just a good stopping place to
submit a PR. At a minimum a new provider should pass all the
integration tests. Everything else is a bonus.
## Step 7: Capabilities
The last step is to add any optional provider capabilities. You can
submit these as a separate PR once the main provider is working.
Don't feel obligated to implement everything at once. In fact, we'd
prefer a few small PRs than one big one. Focus on getting the basic
provider working well before adding these extras.
Operational features have names like `providers.CanUseSRV` and
`providers.CanUseAlias`. The list of optional "capabilities" are
in the file `dnscontrol/providers/providers.go` (look for `CanUseAlias`).
Capabilities are processed early by DNSControl. For example if a
provider doesn't support SRV records, DNSControl will error out
when parsing dnscontrol.js rather than waiting until the API fails
at the very end.
Enable optional capabilities in the nameProvider.go file and run
the integration tests to see what works and what doesn't. Fix any
bugs and repeat.
## Vendoring Dependencies
If your provider depends on other go packages, then you must vendor them. To do this, use [govendor](https://github.com/kardianos/govendor).
If your provider depends on other go packages, then you must vendor them. To do this, use [govendor](https://github.com/kardianos/govendor). A command like this is usually suffient:
```
go get github.com/kardianos/govendor
govendor add +e
```
is usually sufficient.