Merge pull request #870 from deis/dns_readme

refactor(Makefile): better multi-node support

Author: carmstrong

Makefile

@@ -35,14 +35,7 @@ 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
-
-ifeq ($(DEIS_NUM_INSTANCES),1)
-	export SKIP_ROUTER=false
-	START_COMPONENTS=registry logger cache database router
-else
-	export SKIP_ROUTER=true
-	START_COMPONENTS=registry logger cache database
-endif
+START_COMPONENTS=registry logger cache database router
 
 ALL_UNITS = $(foreach C, $(ALL_COMPONENTS), $(wildcard $(C)/systemd/*))
 START_UNITS = $(foreach C, $(START_COMPONENTS), $(wildcard $(C)/systemd/*))
@@ -97,20 +90,7 @@ start: check-fleet
 	@until fleetctl --strict-host-key-checking=false list-units | egrep -q "deis-builder.+(running|failed|dead)"; do printf "\033[0;33mStatus:\033[0m "; fleetctl --strict-host-key-checking=false list-units | grep "builder" | awk '{printf $$3}'; printf "\r" ; sleep 10; done
 	$(call check_for_errors)
 
-	@# router
-	@if [ "$$SKIP_ROUTER" = true ]; then \
-		echo "\033[0;33mYou'll need to configure DNS and start the router manually for multi-node clusters.\033[0m" ; \
-		echo "\033[0;33mRun 'make start-router' to schedule and start deis-router.\033[0m" ; \
-	else \
-		echo "\033[0;33mYour Deis cluster is ready to go! Follow the README to login and use Deis.\033[0m" ; \
-	fi
-
-start-router: check-fleet
-	fleetctl --strict-host-key-checking=false submit router/systemd/*
-	fleetctl --strict-host-key-checking=false start router/systemd/*
-	$(call echo_yellow,"Use 'make status' to monitor the service and note the IP it has been scheduled to.")
-	$(call echo_yellow,"Create a wildcard DNS domain which resolves to this host and use that domain when creating clusters/apps in the README.")
-	$(call echo_yellow,"Your Deis cluster is ready to go! Follow the README to login and use Deis.")
+	$(call echo_yellow,"Your Deis cluster is ready to go! Continue following the README to login and use Deis.")
 
 status: check-fleet
 	fleetctl --strict-host-key-checking=false list-units

README.md

@@ -71,9 +71,7 @@ Use `make run` to start all Deis containers and attach to their log output. This
 $ make run
 ```
 
-## Additional steps for a multi-node cluster
-* Configure local DNS. For a one-node cluster we do this for you: `local.deisapp.com` resolves to the IP of the first VM, 172.17.8.100. Since we cannot know where the `deis-router` container will be running in your cluster, you'll need to setup DNS and resolve a wildcard entry to use for your apps.
-* Because of the DNS quandary, we don't start the deis-router component for you. You'll need to start this manually once DNS is setup: `systemctl start deis-router`.
+Your Vagrant VM is accessible at `local.deisapp.com`. For clusters with more than one node, see our guide to [Configuring DNS](http://docs.deis.io/en/latest/operations/configure-dns/).
 
 ## Testing the cluster
 Integration tests and corresponding documentation can be found under the `test/` folder.

contrib/ec2/README.md

@@ -58,34 +58,17 @@ FLEETCTL_TUNNEL, and issue a `make run` from the project root:
 $ ssh-add ~/.ssh/deis
 $ export FLEETCTL_TUNNEL=ec2-12-345-678-90.us-west-1.compute.amazonaws.com
 $ cd ../.. && make run
-The authenticity of host '54.215.248.50:22' can't be established.
-RSA key fingerprint is 86:10:74:b9:6a:ee:3b:21:d0:0f:b4:63:cc:10:64:c9.
-Are you sure you want to continue connecting (yes/no)? yes
-Warning: Permanently added '54.215.248.50:22' (RSA) to the list of known hosts.
-Job deis-registry.service started on aec641dc.../172.31.21.4
-Job deis-logger.service started on 494dcb6a.../172.31.5.226
-Job deis-database.service started on aec641dc.../172.31.21.4
-Job deis-cache.service started on aec641dc.../172.31.21.4
-Job deis-controller.service started on aec641dc.../172.31.21.4
-Job deis-builder.service started on 494dcb6a.../172.31.5.226
-Job deis-router.service started on aec641dc.../172.31.21.4
-done!
 ```
+The script will deploy Deis and make sure the services start properly.
 
-## Run Deis!
-After that, wait for the components to come up, check which host the controller is
-running on and register with Deis!
+## Configure DNS
+While you can reference the controller and hosted applications with public hostnames provided by EC2, it is recommended for ease-of-use that
+you configure your own DNS records using a domain you own. See [Configuring DNS](http://docs.deis.io/en/latest/operations/configure-dns/) for details.
+
+## Use Deis!
+After that, register with Deis!
 ```
-$ fleetctl list-units
-UNIT                    LOAD    ACTIVE  SUB     DESC            MACHINE
-deis-builder.service    loaded  active  running deis-builder    d9f1f3ea.../172.31.5.62
-deis-cache.service      loaded  active  running deis-cache      d9f1f3ea.../172.31.5.62
-deis-controller.service loaded  active  running deis-controller d9f1f3ea.../172.31.5.62
-deis-database.service   loaded  active  running deis-database   13c5541b.../172.31.5.61
-deis-logger.service     loaded  active  running deis-logger     d9f1f3ea.../172.31.5.62
-deis-registry.service   loaded  active  running deis-registry   4c263e91.../172.31.24.155
-deis-router.service     loaded  active  running deis-router     13c5541b.../172.31.5.61
-$ deis register ec2-12-345-678-90.us-west-1.compute.amazonaws.com:8000
+$ deis register deis.example.org:8000
 username: deis
 password:
 password (confirm):

contrib/rackspace/README.md

@@ -54,35 +54,16 @@ FLEETCTL_TUNNEL, and issue a `make run` from the project root:
 ```console
 $ export FLEETCTL_TUNNEL=23.253.219.94
 $ cd ../.. && make run
-The authenticity of host '23.253.219.94:22' can't be established.
-RSA key fingerprint is ce:3a:c1:3a:ad:11:bd:60:84:8e:60:a8:2f:19:1a:a6.
-Are you sure you want to continue connecting (yes/no)? yes
-Warning: Permanently added '23.253.219.94:22' (RSA) to the list of known hosts.
-Job deis-registry.service scheduled to 73c7d285.../23.253.218.114
-Job deis-logger.service scheduled to 21ad134c.../23.253.217.229
-Job deis-database.service scheduled to 73c7d285.../23.253.218.114
-Job deis-cache.service scheduled to 73c7d285.../23.253.218.114
-Job deis-controller.service scheduled to e5c14be6.../23.253.219.94
-Job deis-builder.service scheduled to e5c14be6.../23.253.219.94
-Job deis-router.service scheduled to 73c7d285.../23.253.218.114
-done!
 ```
+The script will deploy Deis and make sure the services start properly.
+
+### Configure DNS
+You'll need to configure DNS records so you can access applications hosted on Deis. See [Configuring DNS](http://docs.deis.io/en/latest/operations/configure-dns/) for details.
 
 ### Use Deis!
-After that, wait for the components to come up, check which host the controller is
-running on and register with Deis!
+After that, register with Deis!
 ```
-$ fleetctl list-units
-UNIT                    LOAD    ACTIVE  SUB     DESC            MACHINE
-deis-builder.service    loaded  active  running deis-builder    e5c14be6.../23.253.219.94
-deis-cache.service      loaded  active  running deis-cache      73c7d285.../23.253.218.114
-deis-controller.service loaded  active  running deis-controller e5c14be6.../23.253.219.94
-deis-database.service   loaded  active  running deis-database   73c7d285.../23.253.218.114
-deis-logger.service     loaded  active  running deis-logger     21ad134c.../23.253.217.229
-deis-registry.service   loaded  active  running deis-registry   73c7d285.../23.253.218.114
-deis-router.service     loaded  active  running deis-router     73c7d285.../23.253.218.114
-
-$ deis register 23.253.219.94:8000
+$ deis register deis.example.org:8000
 username: deis
 password:
 password (confirm):

docs/operations/configure-dns.rst

@@ -0,0 +1,17 @@
+:title: Configure DNS
+:description: Configure name resolution for your Deis Cluster
+
+.. _configure-dns:
+
+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``).
+
+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:
+
+* ``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``
+
+These records are necessary for multi-node Vagrant as well as any other multi-node deployments of Deis (EC2, Rackspace, etc.).

docs/operations/index.rst

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