From eb77b78c11c21dc83309128a728c7a9c471c2a7f Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Fri, 26 May 2017 08:20:38 -0400 Subject: [PATCH 1/3] Add tips for provider authors. --- docs/writing-providers.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/writing-providers.md b/docs/writing-providers.md index e39ad255f..4c9b57c0b 100644 --- a/docs/writing-providers.md +++ b/docs/writing-providers.md @@ -4,11 +4,25 @@ 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) +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). -More info to follow soon. +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. + +Here are some tips: + +* 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 yourself!). ## Documentation From a2110c5021ec7eaeec75134e0b672b0a02f4508d Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Sat, 27 May 2017 16:13:55 -0400 Subject: [PATCH 2/3] Add unittest docs --- docs/index.md | 4 +++- docs/unittests.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 docs/unittests.md diff --git a/docs/index.md b/docs/index.md index 214225285..0e994f7e2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,10 +11,12 @@ Dnscontrol is a platform for seamlessly managing your dns configuration across a ## [Language Reference]({{site.github.url}}/js): Description of the DNSControl language (DSL). -## [Examples]({{site.github.url}}/examples): DSL examples. +## [Examples]({{site.github.url}}/examples): The DNSControl language by example. ## [Migrating]({{site.github.url}}/migrating): Migrating zones to DNSControl. +## [Testing]({{site.github.url}}/unittests): Unit Testing DNS Data. + ## [github](https://github.com/StackExchange/dnscontrol): Get the source! diff --git a/docs/unittests.md b/docs/unittests.md new file mode 100644 index 000000000..5023aeeb8 --- /dev/null +++ b/docs/unittests.md @@ -0,0 +1,33 @@ +# Unit Testing DNS Data + +## Testing + +DNSControl performs a number of tests during the validation stage. +You can find them in `pkg/normalize/validate.go`. + + +## External tests + +Tests specific to your environment may be added as external tests. +Output the intermediate representation as a JSON file and perform +tests on this data. + +Output the intermediate representation: + + dnscontrol -debugjson foo.json print + +Here is a sample test written in `bash` using the [jq](https://stedolan.github.io/jq/) command. This fails if the number of MX records in the `stackex.com` domain is not exactly 5: + + COUNTMX=$(jq --raw-output Date: Wed, 31 May 2017 13:12:40 -0400 Subject: [PATCH 3/3] Update docs to properly use ROUTE53 in examples (#127) --- docs/_providers/name.com.md | 2 +- docs/_providers/namecheap.md | 2 +- docs/_providers/route53.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_providers/name.com.md b/docs/_providers/name.com.md index 06d3d8b8d..4d26a6e99 100644 --- a/docs/_providers/name.com.md +++ b/docs/_providers/name.com.md @@ -40,7 +40,7 @@ Example javascript (Registrar only. DNS hosted elsewhere): {% highlight js %} var REG_NAMECOM = NewRegistrar("name.com","NAMEDOTCOM"); -var R53 = NewDnsProvider("r53", ROUTE53); +var R53 = NewDnsProvider("r53", "ROUTE53"); D("example.tld", REG_NAMECOM, DnsProvider(R53), A("test","1.2.3.4") diff --git a/docs/_providers/namecheap.md b/docs/_providers/namecheap.md index 10d7761a3..04ef46d3b 100644 --- a/docs/_providers/namecheap.md +++ b/docs/_providers/namecheap.md @@ -49,7 +49,7 @@ Example javascript: {% highlight js %} var namecheap = NewRegistrar("namecheap.com","NAMECHEAP"); -var R53 = NewDnsProvider("r53", ROUTE53); +var R53 = NewDnsProvider("r53", "ROUTE53"); D("example.tld", namecheap, DnsProvider(R53), A("test","1.2.3.4") diff --git a/docs/_providers/route53.md b/docs/_providers/route53.md index 8ede43b76..46839454e 100644 --- a/docs/_providers/route53.md +++ b/docs/_providers/route53.md @@ -7,7 +7,7 @@ jsId: ROUTE53 ## Configuration -By default, you can configure aws setting like the [go sdk configuration](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html). For example you can use environment variables: +By default, you can configure aws setting like the [go sdk configuration](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html). For example you can use environment variables: ``` $ export AWS_ACCESS_KEY_ID=XXXXXXXXX $ export AWS_SECRET_ACCESS_KEY=YYYYYYYYY @@ -34,7 +34,7 @@ Example javascript: {% highlight js %} var REG_NAMECOM = NewRegistrar("name.com","NAMEDOTCOM"); -var R53 = NewDnsProvider("r53", ROUTE53); +var R53 = NewDnsProvider("r53", "ROUTE53"); D("example.tld", REG_NAMECOM, DnsProvider(R53), A("test","1.2.3.4") @@ -47,7 +47,7 @@ DNSControl depends on a standard [aws access key](https://aws.amazon.com/develop ## New domains -If a domain does not exist in your Route53 account, DNSControl +If a domain does not exist in your Route53 account, DNSControl will *not* automatically add it. You can do that either manually via the control panel, or via the command `dnscontrol create-domains` command.