DNS configuration for arbre.app

This repository holds a reproducible configuration for the DNS zone of the domain name arbre.app. The configuration is managed through dnscontrol and deployed by GitHub Actions upon pushes to the master branch. For reproducibility reasons this repository shall be the single source of truth.

Setup

Installation

You must install dnscontrol. You can then check that it is correctly installed:

$ dnscontrol version
dnscontrol v3.9.0-dev

OVH API credentials

The domain is currently registered at OVH. Hence, the OVH API has to be used. To obtain a credential triplet (application key, application secret key and consumer key), head to the following form.

You will be asked to provide a title and a description; just use whatever names makes sense to you.

Ideally, set the the token to never expire (unless it is intended for temporary usage).

Then you should set the following access rules:

Minimal rules (JSON)

{
  "accessRules": [
    {
      "method": "GET",
      "path": "/domain/zone"
    },
    {
      "method": "GET",
      "path": "/domain/zone/arbre.app"
    },
    {
      "method": "GET",
      "path": "/domain/zone/arbre.app/record"
    },
    {
      "method": "GET",
      "path": "/domain/zone/arbre.app/record/*"
    },
    {
      "method": "DELETE",
      "path": "/domain/zone/arbre.app/record/*"
    },
    {
      "method": "POST",
      "path": "/domain/zone/arbre.app/record"
    },
    {
      "method": "PUT",
      "path": "/domain/zone/arbre.app/record/*"
    },
    {
      "method": "POST",
      "path": "/domain/zone/arbre.app/refresh"
    },
    {
      "method": "GET",
      "path": "/domain/arbre.app/nameServer"
    },
    {
      "method": "GET",
      "path": "/domain/arbre.app/nameServer/*"
    },
    {
      "method": "PUT",
      "path": "/domain/arbre.app"
    },
    {
      "method": "POST",
      "path": "/domain/arbre.app/nameServers/update"
    }
  ]
}

This should grant the both the minimal and sufficient rights to manage the domain arbre.app.

Generic list of rules (provided for reference only)

The above rules were derived from the source code. Note that the fields zoneName and serviceName correspond to the domain name (e.g. arbre.app).

GET    /domain/zone
GET    /domain/zone/{zoneName}
GET    /domain/zone/{zoneName}/record
GET    /domain/zone/{zoneName}/record/{id}
DELETE /domain/zone/{zoneName}/record/{id}
POST   /domain/zone/{zoneName}/record
PUT    /domain/zone/{zoneName}/record/{id}
POST   /domain/zone/{zoneName}/refresh
GET    /domain/{serviceName}/nameServer
GET    /domain/{serviceName}/nameServer/{id}
PUT    /domain/{serviceName}
POST   /domain/{serviceName}/nameServers/update

You don't have to enable the IP address whitelist, unless of course you know what you are doing.

Finally, enter the provided triplet in creds.json or as GitHub Actions secrets.

You may verify locally the validity of the credentials with the following (stateless) command:

dnscontrol check-creds ovh OVH

(if you want to delete a token, check the endpoint /me/api/application)

Making changes

Updating the configuration

Everything takes places in the file dnsconfig.js. It is parsed as JavaScript but uses a custom DSL library. The syntax is quite strict (e.g. no trailing commas, etc.), so make sure you perform a dry-run locally, as described below. It is documented here.

Do not use double quotes for textual values containing spaces, they are already properly handled by the tool!

Dry run

You can verify a configuration and safely review the expected changes (without actually modifying anything):

dnscontrol preview

Normal run

To apply the changes, run the following command:

dnscontrol push

In practice this command is automatically run by GitHub Actions so you don't have to (and you shouldn't have to) run it. In case you do, make sure to push the changes.