Skip to main content

Update BIND nameserver zone with Docker hosts via DNS Updates.

Project description

Update BIND nameserver zone with Docker hosts via DNS Updates.

Usage

Docker HostDNS can be run by docker-hostdns wrapper script or directly with python -m docker_hostdns.

usage: docker-entrypoint [-h] [--zone ZONE] [--dns-server DNS_SERVER]
                         [--dns-key-secret DNS_KEY_SECRET]
                         [--dns-key-name DNS_KEY_NAME]
                         [--dns-key-alg {...}]
                         [--name NAME] [--network NETWORK] [--verbose]
                         [--syslog [SYSLOG]] [--clear-on-exit]

Update BIND nameserver zone with Docker hosts via DNS Updates.

optional arguments:
  -h, --help            show this help message and exit
  --zone ZONE           dns zone to update, defaults to "docker"
  --dns-server DNS_SERVER
                        address of DNS server which will be updated, defaults
                        to 127.0.0.1
  --dns-key-secret DNS_KEY_SECRET
                        DNS Server key secret for use when updating zone, use
                        '-' to read from stdin
  --dns-key-name DNS_KEY_NAME
                        DNS Server key name for use when updating zone
  --dns-key-alg {...}
                        DNS Server key algorithm for use when updating zone
  --name NAME           name to differentiate between multiple instances
                        inside same dns zone, defaults to current hostname
  --network NETWORK     network to fetch container names from, defaults to
                        docker default bridge, can be used multiple times
  --verbose, -v         give more output - option is additive, and can be used
                        up to 3 times
  --syslog [SYSLOG]     enable logging to syslog, defaults to "/dev/log", you
                        can provide path to unix socket or uri:
                        <tcp|udp|unix>://<path_or_host>[:<port>]
  --clear-on-exit       clear zone on exit

The --daemonize options is only available when you have installed python-daemon3 package.

Example named.conf zone configuration with key auth:

include "/etc/bind/docker.key";

zone "docker" in {
    type master;
    file "/var/bind/dyn/docker.zone";
    allow-update {
      key "docker-key";
    };
};

docker.key can be generated by:

rndc-confgen -a -c docker.key -k docker-key

And then:

echo 'my base64 key secret' | docker-hostdns --dns-key-name docker-key --dns-key-secret -

Host names

Host name is created by using container name and slugifying & trimming it. So /example2::docker will result with example2-docker. In case of name duplication a “-<number>” will be appended, resulting with eg. example2-docker-1

Following dns records are created for each container, given example hostname and docker zone:

  • IPv4: example.docker

  • IPv4: *.example.docker

  • IPv6: example.docker

  • IPv6: *.example.docker

  • TXT: _container_<name>.docker with container name as value and instance name as <name>

TXT record is used for keeping track of added hosts so when app is stopped or resumed it keeps its state.

Custom host names

You can set custom host name by using container label pl.glorpen.hostname, its content will be used as container name.

Docker Image

Docker image is available at glorpen/hostdns. For help try docker run --rm -it glorpen/hostdns:latest --help.

Remember to mount /run/docker.sock inside container.

Build image from GitHub

  • git clone <repo>

  • cd docker-hostdns/

  • docker build -t "<image name>" .

Docker environment variables

  • DNS_SERVER: address of DNS server which will be updated, defaults to 127.0.0.1

  • DNS_ZONE: DNS zone to update, defaults to docker

  • DNS_KEY_NAME: DNS Server key name for use when updating zone

  • DNS_KEY_SECRET: DNS Server key secret for use when updating zone

  • DNS_KEY_SECRET_FILE: path of file with secret as its content

  • NAME: name to differentiate between multiple instances inside same dns zone, defaults to current hostname

  • NETWORK: network to fetch container names from, defaults to docker default bridge, accepts multiple networks as comma delimited list (e.g. network1,network2,network3,..)

  • VERBOSITY: give more output, accepts 0 to 3, defaults to 0 (equivalent to -v, -vv, -vvv arguments on the command line)

  • SYSLOG: enable logging to syslog, if set true or yes defaults to “/dev/log”, or you can provide path to unix socket or uri: <tcp|udp|unix>://<path_or_host>[:<port>]

  • CLEAR_ON_EXIT: clear zone on exit, defaults to false (accepts true or yes)

Securing DNS secret key

To secure secret key (the dns-key-secret option) you can:

  • passing its contents to env var DNS_KEY_SECRET

  • setting env var DNS_KEY_SECRET_FILE to path of file with secret as its content

Option --dns-key-secret - will be then automatically prepended and secret key piped to docker-hostdns process.

Working with docker-compose

When using docker-compose for development you can create custom docker network and use it as domain names source.

To do this, create docker network with docker network create example-dns and then run Docker HostDNS with --network example-dns argument.

Next, with example docker-compose.yml:

version: '2.2'
services:
  app:
    image: example
    labels:
      pl.glorpen.hostname: example
    networks:
      default: ~
      dns: ~

networks:
  dns:
    external: true
    name: example-dns

you can start container that would be accessible by host as example.docker domain.

2.4.0

  • added dns server name resolving

  • added key algorithm parameter for update request signing

2.3.0

  • configure travis

  • slim docker image

  • fixed and added more tests

  • added more environment variables

2.2.0

  • added environment variables for docker image

2.1.0

  • fixed docker entrypoint exit signal handling

  • added clean-on-exit option to clear used dns zone

2.0.0

  • added Docker image

  • watched network interfaces can be now specified by user

  • container name deduplication now only drops duplicate names

  • single container can have multiple aliases

  • short id and other container aliases are now available as dns names

1.1.1

  • it is now possible to run multiple instances in single dns zone #2 (dvenza)

  • added option to override default instance name for use in txt records

1.1.0

  • possible breaking change: changed dnspython3 package to just dnspython as Py3 is now supported

1.0.4

  • host names are now allowed to have dots in them

1.0.3

  • added tests

  • added proper domain names coversion

  • added a way to keep track of hosts when adding & removing containers

1.0.2

  • fixed error when handling disconnection event without earlier connect one

  • added app exception logging

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docker-hostdns-2.4.0.tar.gz (9.4 kB view details)

Uploaded Source

Built Distribution

docker_hostdns-2.4.0-py3-none-any.whl (10.6 kB view details)

Uploaded Python 3

File details

Details for the file docker-hostdns-2.4.0.tar.gz.

File metadata

  • Download URL: docker-hostdns-2.4.0.tar.gz
  • Upload date:
  • Size: 9.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.3

File hashes

Hashes for docker-hostdns-2.4.0.tar.gz
Algorithm Hash digest
SHA256 961f9184057f509051d5436b9c900368f4da29f3a1c8566dbff77aa95e579dd4
MD5 72e90947c120ba52a88a5a991d66f866
BLAKE2b-256 11666262444b796a8ed6f872a383ee98077e5ba6df3b0bf11a40909aa08c8895

See more details on using hashes here.

File details

Details for the file docker_hostdns-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: docker_hostdns-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 10.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.6.3

File hashes

Hashes for docker_hostdns-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e87c64231ece5810e5aa7f7de19d8ad36488ed07bc78035da3f710b3a0f3c887
MD5 22be5cad2df8bb27eb2c0fc39878cac8
BLAKE2b-256 7cfd043eed9972afff0ef0b2df7e8bda115353e0f94f1e7eb6fea91181278e8d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page