Merge pull request #215 from bacongobbler/docs-quickstart-cleanup

ref(docs): clean up quickstart documentation

Author: Matthew Fisher

docs/src/installing-deis/installing-the-deis-platform.md

@@ -37,22 +37,6 @@ $ helm repo add deis https://github.com/deis/charts
 $ helm fetch deis/deis
 ```
 
-## Set up the Deis Router
-
-Now that you have the Deis chart, you'll need to make a minor edit to the
-`deis-router-rc.yaml` Kubernetes manifest file to prepare the router to accept
-incoming traffic on a domain of your choice. Follow the following steps to make
-the edit:
-
-1. Open the `$(helm home)/workspace/charts/deis/manifests/deis-router-rc.yaml`
-file in your favorite editor. Note that `$(helm home)` executes the command to get
-the directory that helm uses to store its config and all its charts. See
-http://helm.readthedocs.org/en/latest/workspace/ for details.
-2. Replace `example.com` under `metadata.annotations.deis.io/routerConfig` with
-the domain of your choice. This will be called the _platform domain_. You may choose
-any domain, but the `Routing Traffic` section below details how to configure DNS or your
-host to use that domain properly, so you may want to read that section before proceeding.
-
 ## Launch Your Deis Cluster
 
 Now that you have it prepared, launch the Deis cluster with:
@@ -71,137 +55,6 @@ $ kubectl get pods --namespace=deis
 
 Once you see all of the pods in the `READY` state, your Deis platform is running on a cluster!
 
-## A Note on Routing Traffic
-
-As mentioned above, the Deis router component is responsible for accepting traffic
-from outside the Kubernetes cluster and directing appropriately. It uses the
-incoming request's HTTP `Host` header to direct traffic to Deis components and
-to applications deployed via Deis.
-
-### Getting Traffic to the Cluster
-
-You already configured the router with a platform domain in the above setup instructions.
-This section details how to configure DNS and/or your local `/etc/hosts` file so that
-traffic bound for `*.your-platform.domain` will make it to your Kubernetes cluster
-and the Deis router.
-
-#### Using an Automatically Provisioned Load Balancer
-
-If your Kubernetes cluster and the underlying infrastructure
-support it, the Deis router's service (which is of `type:
-LoadBalancer`) will automatically provision an "external"
-(external to the Kubernetes cluster) load balancer.  On AWS,
-for instance, this takes the form of an ELB, while on Google
-Container Engine, it takes the form of a routing rule.
-
-If it is supported, you will be able to find the DNS name or
-IP(s) of the external load balancer like so:
-
-```
-$ kubectl describe service deis-router --namespace=deis
-```
-
-Examine the `LoadBalancer Ingress` field to find the DNS
-name or IP(s).  The former can be added to DNS as a CNAME,
-while the latter can be added as an A record.
-
-#### Creating Your Own Load Balancer
-
-On Kubernetes clusters and underlying infrastructure that
-do not support the automated provisioning of an external
-load balancer for the Deis router, you may provision your
-own and add _all_ minion nodes of the Kubernetes cluster to
-the pool.
-
-The load balancer must pass incoming traffic on the
-following ports to the _same_ ports on the Kubernetes
-worker nodes:
-
-* 80
-* 443
-* 2222
-* 9090
-
-The Deis router component listens to those ports on any
-host it runs on.  Since not _all_ nodes are likely to
-be running the router, a health check should be used to
-determine which node(s) can serve requests.  The router's
-healthcheck should use the HTTP protocol, port `9090`, and
-the request path `/healthz`.
-
-Load balancer idle timeouts should be set to at least `1200`
-seconds so connections do not close prematurely during longer
-running requests such as application deployments.
-
-#### Without a Load Balancer
-
-On some platforms (Vagrant, for instance) a load balancer is
-not an easy or practical thing to provision.  In these cases,
-one can directly identify the public IP of a Kubernetes node
-that is hosting a router pod and use that information to
-configure DNS or the local `/etc/hosts` file.
-
-You can find the IP address of a node using `kubectl`:
-
-```
-$ kubectl get pods --namespace=deis | grep deis-router
-deis-router-ih25q           1/1       Running   0          2h
-```
-
-Using the pod name determined through the above, one can
-use `kubectl` to determine what node the pod is running on:
-
-```
-$ kubectl describe pod deis-router-ih25q --namespace=deis
-```
-
-The `Node` field of the response should provide an IP:
-
-```
-Node:				10.245.1.3/
-```
-
-If the IP is public, this can be used to configure DNS or the
-local `/etc/hosts` file.
-
-In your `/etc/hosts` file, add an entry like this:
-
-```
-10.245.1.3    example.com deis.example.com
-```
-
-This route will get you started, though you may find that you have to
-manually maintain this file.
-
-#### Using a DNS Service
-
-With any of the avenues described above, some hassle may be spared by
-leveraging a service such as `xip.io`, which will not require any
-editing of DNS records or local `/etc/hosts` files.
-
-Simply determine the correct IP to route your traffic to (as described
-above), then configure the router's platform domain to be `<ip>.xip.io`
-
-### Testing
-
-To test that traffic reaches its intended destination, a request can be
-sent to the Deis controller like so:
-
-```
-curl http://deis.<platform domain>/v2/
-```
-
-Since such requests require authentication, a response such as
-the following is an indicator of success:
-
-```
-{"detail":"Authentication credentials were not provided."}
-```
-
-## Next Steps
-
-Now that you've finished provisioning a cluster, start [Using Deis][] to deploy your first
-application on Deis.
 
 [install deisctl]: installing-deisctl.md
 [helm]: http://helm.sh

docs/src/installing-deis/quickstart.md

@@ -14,19 +14,20 @@ Choose one of the following providers and deploy a new kubernetes cluster:
 - [Google Container Engine](https://cloud.google.com/container-engine/docs/before-you-begin)
 - [Vagrant](http://kubernetes.io/v1.1/docs/getting-started-guides/vagrant.html)
 
-## Configure DNS
-
-See [Configuring DNS][] for more information on properly setting up your DNS records with Deis.
-
 ## Install Deis Platform
 
 Now that you've finished provisioning a cluster, please [Install the Deis Platform][install deis].
 
+## Configure DNS
+
+See [Configuring DNS][] for more information on properly setting up your DNS records with Deis.
+
 ## Register a User
 
 Once your cluster has been provisioned and the Deis Platform has been installed, you can
 [install the client][client] and [register your first user][register]!
 
+
 [client]: ../using-deis/installing-the-client.md
 [configuring object storage]: configuring-object-storage.md
 [configuring dns]: ../managing-deis/configuring-dns.md

docs/src/managing-deis/configuring-dns.md

@@ -18,16 +18,67 @@ Apps can then be accessed by browsers at `appname.myapps.com`, and the controlle
 
 These records are necessary for all deployments of Deis other than Vagrant clusters.
 
-## Using xip.io
+## DNS without a Load Balancer
 
-For local Vagrant clusters or for dev clusters, you can use [xip][] to reference the IP of your load balancer. For example:
+On some platforms (Vagrant, for instance), a load balancer is not an easy or practical thing to
+provision. In these cases, one can directly identify the public IP of a Kubernetes node that is
+hosting a router pod and use that information to configure DNS or the local `/etc/hosts` file.
 
-    $ deis register http://deis.10.21.12.2.xip.io
+You can find the IP address of a node using `kubectl`:
 
-You would then create the cluster with `10.21.12.2.xip.io` as the cluster domain.
+```
+$ kubectl get pods --namespace=deis | grep deis-router
+deis-router-ih25q           1/1       Running   0          2h
+```
+
+Using the pod name determined through the above, one can
+use `kubectl` to determine what node the pod is running on:
+
+```
+$ kubectl describe pod deis-router-ih25q --namespace=deis
+```
+
+The `Node` field of the response should provide an IP:
+
+```
+Node:				10.245.1.3/
+```
+
+If the IP is public, this can be used to configure DNS or the
+local `/etc/hosts` file.
+
+An easy way to configure wildcard DNS is to use [xip.io][] to reference the IP of the node running
+your router. For example:
+
+    $ deis register http://deis.10.245.1.3.xip.io
 
 Note that xip does not seem to work for AWS ELBs - you will have to use an actual DNS record.
 
+Alternatively, in your `/etc/hosts` file, add an entry like this:
+
+```
+10.245.1.3    example.com deis.example.com
+```
+
+This will get you started, though you may find that you have to manually maintain this file as you
+create and deploy more applications to the cluster.
+
+## Testing
+
+To test that traffic reaches its intended destination, a request can be
+sent to the Deis controller like so:
+
+```
+curl http://deis.example.com/v2/
+```
+
+Since such requests require authentication, a response such as
+the following is an indicator of success:
+
+```
+{"detail":"Authentication credentials were not provided."}
+```
+
 [AWS recommends]: https://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-domain-names-with-elb.html
 [load balancer]: configuring-load-balancers.md
 [Route 53]: http://aws.amazon.com/route53/

docs/src/managing-deis/configuring-load-balancers.md

@@ -5,8 +5,9 @@ Deis includes multiple routers scheduled to the cluster as part of the router me
 These ports need to be open on the load balancers:
 
 * 80 (for application traffic and for API calls to the controller)
+* 443 (for secure traffic to the controller and applications, if applicable)
 * 2222 (for traffic to the builder)
 
 If you want to configure SSL termination on your load balancer, see [Platform SSL](platform-ssl.md).
 
-A health check should be configured on the load balancer to send an HTTP request to /health-check at port 80 on all nodes in the Deis cluster. The health check endpoint returns an HTTP 200. This enables the load balancer to serve traffic to whichever hosts happen to be running the deis-router component at any moment.
+A health check should be configured on the load balancer to send an HTTP request to /healthz at port 9090 on all nodes in the Deis cluster. The health check endpoint returns an HTTP 200. This enables the load balancer to serve traffic to whichever hosts happen to be running the router component at any moment.