README
¶
⚠ As of Docker v1.12
waglis now obsolete, as Swarm is integrated into the Docker Engine and has built in service discovery and routing features. You should not be usingwaglanymore. ⚠
wagl: DNS Service Discovery for Docker Swarm v1.0
wagl runs inside your Docker Swarm cluster and provides
DNS-based service discovery (using DNS A and SRV records) and
simple load balancing by rotating the list of IP addresses in
DNS records.
For instance, if you run your API container with command:
docker run -d -l dns.service=api -p 80:80 nginx
other containers in the cluster will be able to reach this container using URL
http://api.swarm. It is a minimalist solution, yet handles most of the
basic DNS service discovery functionality well ––but we're open to pull
requests.
wagl runs inside a container in the Swarm cluster (preferably on manager
nodes) and is easy to deploy.
User Guide
- wagl Command-Line Interface
- Deploying wagl
- Service Naming for DNS
- DNS Forwarding for External Domains
- Best Practices
Demo
Watch the demo at: https://www.youtube.com/watch?v=H7dr6lZqw6I
5-Minute Tutorial
Let's create a Docker Swarm cluster with docker-machine and deploy
a wagl container to serve as a DNS server to this cluster:
Step 0: Download docker client and docker-swarm on your machine.
Step 1: Obtain a Swarm discovery token:
$ docker run --rm swarm create
9746027c20071fdabf9347203fc380fa
Step 2: Create a single master and 3-node Swarm cluster with docker-machine
TOKEN=9746027c20071fdabf9347203fc380fa # <-- paste your token
docker-machine create -d virtualbox --swarm --swarm-master --swarm-discovery token://$TOKEN swarm-m && \
for i in {0..2}; do docker-machine create -d virtualbox --swarm --swarm-discovery token://$TOKEN swarm-$i; done
Step 3: Deploy the wagl DNS container to the Swarm master node:
docker-machine ssh swarm-m
and then run:
docker run -d --restart=always \
--link=swarm-agent-master:swarm \
-v /var/lib/boot2docker/ca.pem:/certs/ca.pem \
-v /var/lib/boot2docker/server.pem:/certs/cert.pem \
-v /var/lib/boot2docker/server-key.pem:/certs/key.pem \
-p 53:53/udp \
--name=dns \
ahmet/wagl \
wagl --swarm tcp://swarm:3376 \
--swarm-cert-path /certs
The following command deploys a wagl container (named dns) pointing it to a
“Swarm manager” running on the same node on :3376 and starts listening for DNS
queries on port 53.
After the container is working (verify with docker ps), exit the SSH prompt.
Step 4: Schedule some web server containers on your cluster.
Pay attention to how we use Docker labels (-l argument) to name our services:
$ eval $(docker-machine env --swarm swarm-m)
$ docker run -d -l dns.service=blog -p 80:80 nginx
$ docker run -d -l dns.service=api -l dns.domain=billing -p 80:80 nginx
$ docker run -d -l dns.service=api -l dns.domain=billing -p 80:80 nginx
Step 5: Verify the DNS works! Start a container in the cluster
with --dns argument as IP address where the dns container running (in this
case, master node) and make a request for http://blog.swarm:
$ master=$(docker-machine ip swarm-m)
$ docker run -it --dns $master busybox
/ # wget -qO- http://blog.swarm
Connecting to blog.swarm (192.168.99.101:80)
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>...
Let's quit this container and launch a Debian container in the cluster to make DNS lookups
to these api containers for A/SRV records:
$ docker run -it --dns $master debian
/# apt-get -q update && apt-get -qqy install dnsutils
...
/# dig +short A api.billing.swarm
192.168.99.103
192.168.99.102
/# dig +short SRV _api._tcp.billing.swarm
1 1 80 192.168.99.102.
1 1 80 192.168.99.103.
As you can notice the IP addresses are returned in random order for very naive load-balancing via the DNS records.
This is wagl in a nutshell. Play and experiment with it!
Not Implemented Properties
Some features are not implemented for the sake of minimalism. Please be aware of these before using.
- DNSSEC
- IPv6 records (such as type AAAA)
- Not-so-needed record types (NS, SOA, MX etc)
- HTTP REST API to query records
- Proper and configurable DNS message exchange timeouts
- DNS over TCP: currently we only do UDP, I have no idea what happens to large DNS queries or answers.
- Recursion on external nameservers: We just randomly pick an external NS to forward the request and if that fails we don't try others, we just call it failed.
- Staleness checks are fragile to system clock changes because Go language does not have monotonically increasing clock implementation.
For the not implemented features, we return NOTIMP status code in DNS answers
and any server failure returns SERVFAIL status code.
Authors
License
This project is licensed under Apache License Version 2.0. Please refer to LICENSE.
Disclaimer
This project is affiliated neither with Microsoft Corporation nor Docker Inc.
Why the name?
It turns out the scientists obvserved that the honeybees coming back from a food source to the bee hive, they tended to waggle about excitedly in a figure 8 pattern which shares the location of the food source with other bees. This is called “The Waggle Dance”. It is actually pretty amazing, you should just watch the video.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps
|
|
|
_workspace/src/github.com/codegangsta/cli
Package cli provides a minimal framework for creating and organizing command line Go applications.
|
Package cli provides a minimal framework for creating and organizing command line Go applications. |
|
_workspace/src/github.com/miekg/dns
Package dns implements a full featured interface to the Domain Name System.
|
Package dns implements a full featured interface to the Domain Name System. |
|
_workspace/src/github.com/miekg/dns/idn
Package idn implements encoding from and to punycode as speficied by RFC 3492.
|
Package idn implements encoding from and to punycode as speficied by RFC 3492. |
|
Package rrgen finds out tasks eligible for having DNS records and generates th DNS Resource Records for these.
|
Package rrgen finds out tasks eligible for having DNS records and generates th DNS Resource Records for these. |
|
Package rrstore provides concurrency-safe storage for DNS Resource Records (RRs).
|
Package rrstore provides concurrency-safe storage for DNS Resource Records (RRs). |
|
Package swarm provides the cluster state and tasks that are going to be load balanced in the cluster.
|
Package swarm provides the cluster state and tasks that are going to be load balanced in the cluster. |
|
Package task describes a task resource in the cluster
|
Package task describes a task resource in the cluster |
|
Package tlsconfig provides primitives to retrieve secure-enough TLS configurations for both clients and servers.
|
Package tlsconfig provides primitives to retrieve secure-enough TLS configurations for both clients and servers. |