feat(router): support for multiple routers

This commit adds functionality to the Makefile to launch multiple
routers, which is the first step towards a HA Deis installation.

Additional routers can later be added to an existing cluster by setting
DEIS_FIRST_ROUTER to start the router numbering at something other than 1.

Note that load balancing / DNS records must still be set up manually.

We also have the router publish its host:port to the namespace
/deis/routers/$HOST, as we have the possibility of multiple routers
in the cluster.

closes #922

Makefile

@@ -10,6 +10,14 @@ ifndef DEIS_NUM_INSTANCES
 	DEIS_NUM_INSTANCES = 1
 endif
 
+ifndef DEIS_NUM_ROUTERS
+	DEIS_NUM_ROUTERS = 1
+endif
+
+ifndef DEIS_FIRST_ROUTER
+	DEIS_FIRST_ROUTER = 1
+endif
+
 # TODO refactor to support non-vagrant installations, since this Makefile
 # is now used by the various contrib/ scripts.
 define ssh_all
@@ -34,8 +42,8 @@ endef
 
 # due to scheduling problems with fleet 0.2.0, start order of components
 # is fragile. hopefully this can be changed soon...
-ALL_COMPONENTS=builder cache controller database logger registry router
-START_COMPONENTS=registry logger cache database router
+ALL_COMPONENTS=builder cache controller database logger registry
+START_COMPONENTS=registry logger cache database
 
 ALL_UNITS = $(foreach C, $(ALL_COMPONENTS), $(wildcard $(C)/systemd/*))
 START_UNITS = $(foreach C, $(START_COMPONENTS), $(wildcard $(C)/systemd/*))
@@ -67,10 +75,22 @@ pull:
 
 restart: stop start
 
+routers:
+	$(call echo_yellow,"Starting $(DEIS_NUM_ROUTERS) router(s)...")
+	@router_num=$(DEIS_FIRST_ROUTER) ; \
+	i=1 ; while [ $$i -le $(DEIS_NUM_ROUTERS) ] ; do \
+			cp router/systemd/deis-router.service ./deis-router.$$router_num.service ; \
+			fleetctl --strict-host-key-checking=false submit ./deis-router.$$router_num.service ; \
+			fleetctl --strict-host-key-checking=false start ./deis-router.$$router_num.service ; \
+			rm -f ./deis-router.$$router_num.service ; \
+			i=`expr $$i + 1` ; \
+			router_num=`expr $$router_num + 1` ; \
+	done
+
 run: install start
 
-start: check-fleet
-	@# registry logger cache database (router)
+start: check-fleet routers
+	@# registry logger cache database
 	$(call echo_yellow,"Starting Deis! Deis will be functional once all services are reported as running... ")
 	fleetctl --strict-host-key-checking=false start $(START_UNITS)
 	$(call echo_yellow,"Waiting for deis-registry to start (this can take some time)... ")

docs/operations/configure-dns.rst

@@ -6,12 +6,20 @@
 Configure DNS
 -------------
 
-For a one-node cluster, both deis-router and deis-controller will run on the same host. For convenience, we've created the DNS record ``local.deisapp.com`` which resolves to the IP of the first VM, 172.17.8.100.
-You can use ``local.deisapp.com`` to both log into the controller and to access applications that you've deployed (they will be subdomains of ``local.deisapp.com``, like ``happy-unicorn.local.deisapp.com``).
+For local one-node Vagrant clusters, we've created the DNS record ``local.deisapp.com`` which resolves to the IP of the first VM, 172.17.8.100.
+You can use ``local.deisapp.com`` to both log into the controller and to access applications that you've deployed (they will be subdomains of ``local.deisapp.com``, like ``happy-unicorn.local.deisapp.com``). So, no further DNS configuration is necessary.
 
-On a multi-node cluster, however, the router and controller will likely be scheduled on separate machines. Since we cannot know the IP addresses ahead of time, you'll need to setup resolution yourself using your own domain (unfortunately, wildcard hostnames are not permitted in ``/etc/hosts``). The records should be as follows:
+For a non-local one-node cluster, we schedule and launch one router, and deis-router and deis-controller will run on the same host. So, both DNS records can be configured to point to this one machine.
 
+On a multi-node cluster, however, there are probably multiple routers, and the controller will likely be scheduled on a separate machine. As mentioned in :ref:`configure-load-balancers`, a load balancer is recommended in this scenario.
+
+Note that the controller will eventually live behind the routers so that all external traffic will flow through the load balancer - configuring a DNS record which points to a service whose IP could change is less than ideal.
+
+Necessary DNS records
+---------------------
+
+The DNS records for Deis should be configured as such:
 * ``deis.example.org`` should resolve to the IP of the machine that runs ``deis-controller``
-* ``*.deis.example.org`` (a wildcard DNS entry) should resolve to the IP of the machine that runs ``deis-router``
+* ``*.deis.example.org`` (a wildcard DNS entry) should point to the load balancer (or the same machine for 1-node Vagrant, or any single instance of ``deis-router`` if one likes to live life on the edge)
 
-These records are necessary for multi-node Vagrant as well as any other multi-node deployments of Deis (EC2, Rackspace, etc.).
+These records are necessary for all deployments of Deis (EC2, Rackspace, multi-node Vagrant) except for a local, one-node Vagrant setup, which can use ``local.deisapp.com``.

docs/operations/configure-load-balancers.rst

@@ -0,0 +1,15 @@
+:title: Configure load balancers
+:description: Configure load balancers for your Deis Cluster
+
+.. _configure-load-balancers:
+
+Configure load balancers
+------------------------
+
+For a one-node Deis cluster, there is one router and one controller, so load balancing is unnecessary. You can proceed with the next section: :ref:`configure-dns`.
+
+On a multi-node cluster, however, there are probably multiple routers scheduled to the cluster, and these can potentially move hosts. Therefore, it is recommended that you configure a load balancer to operate in front of the Deis cluster to serve application traffic. A simple configuration is one that has all Deis machines listed in its configuration file, but a host is only considered 'healthy' when it is serving traffic on port 80. This enables the load balancer to serve trafic to whichever hosts happen to be running the deis-router component at any one time.
+
+The load balancer is also the suggested SSL termination point, as SSL is not currently supported between Deis components.
+
+Further documentation around load balancers is planned for Deis 1.0.

docs/operations/index.rst

@@ -15,4 +15,5 @@ Operations Guide
     provision-controller
     register-admin-user
     manage-controller
+    configure-load-balancers
     configure-dns

router/bin/boot

@@ -12,7 +12,7 @@ set -eo pipefail
 # configure etcd
 export ETCD_PORT=${ETCD_PORT:-4001}
 export ETCD="$HOST:$ETCD_PORT"
-export ETCD_PATH=${ETCD_PATH:-/deis/router}
+export ETCD_PATH=${ETCD_PATH:-/deis/router/$HOST}
 export ETCD_TTL=${ETCD_TTL:-10}
 
 # wait for etcd to be available

router/systemd/deis-router.service

@@ -11,3 +11,6 @@ ExecStop=/usr/bin/docker rm -f deis-router
 
 [Install]
 WantedBy=multi-user.target
+
+[X-Fleet]
+X-Conflicts=deis-router.*.service