Creating Records

Primer on Docker Labels

Labels are key-value pairs that can be attached to various objects in the Docker daemon. DockNS only cares about labels attached to containers (both running and stopped), all other labels are irrelevant.

There are 3 ways in which labels are defined on a container:

1. Docker CLI - When creating/running a container, labels can be specified using the --label argument (Docker docs) (Ex. docker run --label key=value my_image).

2. Docker Compose - In the compose file, each service can have a labels array with key=value or a labels map with key: value for each label (Docker docs). The examples below use the compose syntax for demonstration.

3. Dockerfile - When creating an image, labels can be applied to the image using the LABEL instruction (Docker docs). When a container is created from a labeled image, the container will then have the same labels as the image, unless overwritten using the CLI or Compose.

Using Labels to Create Records

The general format is dockns.<server id>.<record index>.<parameter>=<value>, where:

• <server id> is the name of the server as defined in config.toml.

• <record index> is the index of the record for <server id>. If omitted, defaults to 0.

• <parameter> is the DNS parameter to set.

• <value> is the value to set the parameter to.

All records must have a record parameter which specifies the type of the record being created. The currently supported record types are A, AAAA, CNAME, SRV, and TXT.

Additionally, all records must have a name parameter for the name of the record and a ttl (time to live). The exact contents of name depend on which name server is being used, but most of the time it will be a fully qualified domain name (domain.tld, subdomain.domain.tld, my.app.domain.tld, etc.). ttl is just how long the record should be cached in seconds. A typical value for ttl is 3600 which equates to 1 hour.

The rest of the parameters depend on the record type. The ip parameter is used by A and AAAA records (using IPv4 and IPv6 addresses respectively), and target_domain is used by CNAME records. Parameters for other record types are available on the labels reference page.

Examples

The following examples all use the Docker Compose yaml format for demonstration, but the same labels can be set via the CLI as discussed above. The defined server ids for the examples are: internaldns, external_cloudflare, and peer_technitium.

Simple A Record

services:
  my_service:
    image: my_image:latest
    labels:
      # Define an A record which points to this machine (ip: 192.168.1.50)
      - dockns.internaldns.record=A
      - dockns.internaldns.name=my_app.domain.tld
      - dockns.internaldns.ip=192.168.1.50
      - dockns.internaldns.ttl=3600

Simple CNAME Record

services:
  my_service:
    image: my_image:latest
    labels:
      # Define an CNAME record which points an ingress reverse proxy
      - dockns.internaldns.record=CNAME
      - dockns.internaldns.name=app.domain.tld
      - dockns.internaldns.target_domain=proxy.domain.tld
      - dockns.internaldns.ttl=3600

A Record on Multiple Name Servers

services:
  my_service:
    image: my_image:latest
    labels:
      # Labels can also be specified with map syntax instead of list syntax
      dockns.external_cloudflare.record: A
      dockns.external_cloudflare.name: my_app.domain.tld
      dockns.external_cloudflare.ip: 1.2.3.4
      dockns.external_cloudflare.ttl: 3600

      dockns.peer_technitium.record: A
      dockns.peer_technitium.name: my_app.domain.tld
      dockns.peer_technitium.ip: 10.0.0.50
      dockns.peer_technitium.ttl: 3600

Multiple Records on One Server

services:
  my_service:
    image: my_image:latest
    labels:
      # Both no index, and index 0 form the same record.
      # Record index 0 is implied
      - dockns.internaldns.record=A
      - dockns.internaldns.0.name=my_app.domain.tld
      - dockns.internaldns.ip=192.168.1.50
      - dockns.internaldns.0.ttl=3600

      # Additional records MUST specify their index
      - dockns.internaldns.1.record=TXT
      - dockns.internaldns.1.name=my_app_txt.domain.tld
      - dockns.internaldns.1.ip=My Text Data
      - dockns.internaldns.1.ttl=3600

Using Default Values

config.toml

# Global Defaults
[record_defaults]
ttl = 3600 # Define TTL to be 1 hour for all records

[name_servers.internaldns]
# ... some options omitted for brevity ...
record_defaults = {
  A.ip = "192.168.1.50"
}

[name_servers.peer_technitium]
# ... some options omitted for brevity ...
record_defaults = {
  # Default TTL overridden for all records on the peer_technitium server
  ttl = 1800
  A.ip = "10.0.0.50"
}

docker-compose.yaml

services:
  my_service:
    image: my_image:latest
    labels:
      # ip and ttl can be omitted because they have defaults in `config.toml`
      - dockns.internaldns.record=A
      - dockns.internaldns.name=my_app.domain.tld

      # ip and ttl can be omitted because they have defaults in `config.toml`
      - dockns.peer_technitium.record=A
      - dockns.peer_technitium.name=my_app.domain.tld

      # TTL can still be specified, overriding any defaults applied
      - dockns.peer_technitium.ttl=300