docs(*): documenting basedomain and ingress setup

README.md

@@ -13,51 +13,11 @@ Draft handles the heavy lifting involved in taking source code and deploying it
 - Packages a [Helm][] chart from application source code
 - Installs the chart to Kubernetes, deploying the application
 
-## Usage
+## Installation
 
-### Dependencies
+Review the [Installation Guide][Installation Guide] to configure and install Draft on to your Kubernetes cluster.
 
-- Draft will need a running Kubernetes cluster to deploy your app. [Minikube](https://github.com/kubernetes/minikube) is a great free option.
-- Draft expects [Helm](https://github.com/kubernetes/helm) to be installed on your Kubernetes cluster. Download [`helm` v2.4.x](https://github.com/kubernetes/helm/releases) and
-do a `helm init` first, as described in [Installing Helm][].
-- Draft needs to push images to a Docker registry, so you'll need to configure Draft with your Docker registry credentials. If don't already have one, you can create a Docker registry for free on either [Dockerhub.com](https://dockerhub.com) or [Quay.io](https://quay.io).
-
-### Install Draft
-
-Because Draft is currently experimental, there is no stable release out yet and users are expected
-to be using the latest build of Draft for testing. Canary releases of the Draft client can be found
-at the following links:
-
- - [Linux amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-linux-amd64.tar.gz)
- - [macOS amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-darwin-amd64.tar.gz)
- - [Windows amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-windows-amd64.tar.gz)
-
-Unpack the Draft binary and add it to your PATH and you are good to go!
-
-
-### Configure Draft
-
-To install the server-side of Draft, use `draft init` with your credentials to let Draft communicate
-with a Docker registry by using the following command:
-
-```
-$ draft init --set registry.url=docker.io,registry.org=changeme,registry.authtoken=changeme
-```
-
-The auth token field follows the format of Docker's X-Registry-Auth header.
-For credential-based logins such as Docker Hub and Quay, use:
-
-```
-$ echo '{"username":"jdoe","password":"secret","email":"jdoe@acme.com"}' | base64
-```
-
-For token-based logins such as Google Container Registry and Amazon ECR, use:
-
-```
-$ echo '{"registrytoken":"9cbaf023786cd7"}' | base64
-```
-
-### Take Draft for a Spin
+## Take Draft for a Spin
 
 Climb aboard and explore the [Getting Started Guide][Getting Started] - you'll soon be sailing!
 
@@ -79,6 +39,7 @@ This software contains code from [Helm][], which is covered by the Apache v2.0 l
 You can read third-party software licenses [here][Third-Party Licenses].
 
 
+[Installation Guide]: docs/install.md
 [Getting Started]: docs/getting-started.md
 [hacking]: docs/contributing/hacking.md
 [`helm` v2.4.2]: https://github.com/kubernetes/helm/releases/tag/v2.4.2

docs/getting-started.md

@@ -1,7 +1,7 @@
 # Getting Started
 
-This document shows how to deploy a "Hello World" app with Draft. To follow along, be sure you
-have Draft up and installed according to the [README](../README.md#install-draft).
+This document shows how to deploy a "Hello World" app with Draft. If you havent done so already,
+be sure you have Draft installed according to the [Installation Guide][Installation Guide].
 
 ## App setup
 
@@ -148,7 +148,7 @@ The push refers to a repository [docker.io/microsoft/tufted-lamb]
 Now when we run `curl http://$SERVICE_IP`, our first app has been deployed and updated to our
 [Kubernetes][] cluster via Draft!
 
-
+[Installation Guide]: install.md
 [Helm]: https://github.com/kubernetes/helm
 [Kubernetes]: https://kubernetes.io/
 [Python]: https://www.python.org/

docs/ingress.md

@@ -0,0 +1,51 @@
+## What is Ingress
+
+Ingress is a way to route traffic from the internet to services within your Kubernetes cluster,
+without creating a load-balancer for each service. For more information, review the
+[Kubernetes Ingress Documentation][Kubernetes Ingress Documentation]
+
+## Installing an Ingress Controller
+
+While there are many ingress controllers available within the Kubernetes Community, for
+simplicity, this guide will use the nginx-ingress from the stable helm charts, but you are
+welcome to use any ingress controller.
+
+These documents assume you are connected to a Kubernetes cluster running in a cloud-provider.
+
+**NOTE:** If you are running in minikube, these steps will not work as desired. Additional documentation
+about running draft on a minikube cluster will be made available shortly.
+
+```shell
+$ helm install stable/nginx-ingress --namespace=kube-system --name=nginx-ingress
+```
+
+After you've installed the nginx-ingress controller, wait for a Load Balancer to be created with:
+
+```shell
+$ kubectl --namespace kube-system get services -w nginx-ingress-nginx-ingress-controller
+```
+
+## Point a wildcard domain
+
+Draft uses a wildcard domain to make accessing draft-created applications easier.
+
+Using a domain that you manage, create a DNS wildcard `A Record` pointing to the ingress IP address.
+
+**NOTE:** you are welcome to use `*.draft.example.com` or any other wildcard domain.
+
+Remember the domain you use, it will be needed in the next step of installation as the basedomain.
+
+| Name          | Type | Data                    |
+|---------------|------|-------------------------|
+| *.example.com | A    | <ip address from above> |
+
+## Next steps
+
+Once you have an ingress controller installed and configured on your cluster, you're ready
+to install Draft. 
+
+Continue with the [Installation Guide][Installation Guide]!
+
+
+[Installation Guide]: docs/install.md#install-draft
+[Kubernetes Ingress Documentation]: https://kubernetes.io/docs/concepts/services-networking/ingress/

docs/install.md

@@ -0,0 +1,48 @@
+## Dependencies
+
+- Draft will need a running Kubernetes cluster to deploy your app. [Minikube](https://github.com/kubernetes/minikube) is a great free option.
+- Draft expects [Helm](https://github.com/kubernetes/helm) to be installed on your Kubernetes cluster. Download [`helm` v2.4.x](https://github.com/kubernetes/helm/releases) and
+do a `helm init` first, as described in [Installing Helm][].
+- Draft needs to push images to a Docker registry, so you'll need to configure Draft with your Docker registry credentials. If don't already have one, you can create a Docker registry for free on either [Dockerhub.com](https://dockerhub.com) or [Quay.io](https://quay.io).
+- An ingress controller installed within your Kubernetes cluster with a wildcard domain pointing to it. Review the [Ingress Guide][Ingress Guide] for more information about what Draft expects and how to set up an ingress controller.
+
+## Install Draft
+
+Because Draft is currently experimental, there is no stable release out yet and users are expected
+to be using the latest build of Draft for testing. Canary releases of the Draft client can be found
+at the following links:
+
+ - [Linux amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-linux-amd64.tar.gz)
+ - [macOS amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-darwin-amd64.tar.gz)
+ - [Windows amd64](https://azuredraft.blob.core.windows.net/draft/draft-canary-windows-amd64.tar.gz)
+
+Unpack the Draft binary and add it to your PATH.
+
+## Configure Draft
+
+To install the server-side of Draft, use `draft init` with your ingress' basedomain and credentials
+to let Draft communicate with a Docker registry by using the following command:
+
+```
+$ draft init --set registry.url=docker.io,registry.org=changeme,registry.authtoken=changeme,basedomain=changeme
+```
+
+The auth token field follows the format of Docker's X-Registry-Auth header.
+For credential-based logins such as Docker Hub and Quay, use:
+
+```
+$ echo '{"username":"jdoe","password":"secret","email":"jdoe@acme.com"}' | base64
+```
+
+For token-based logins such as Google Container Registry and Amazon ECR, use:
+
+```
+$ echo '{"registrytoken":"9cbaf023786cd7"}' | base64
+```
+
+## Take Draft for a Spin
+
+Once you've completed the above steps, you're ready to climb aboard and explore the [Getting Started Guide][Getting Started] - you'll soon be sailing!
+
+[Ingress Guide]: ingress.md
+[Getting Started]: getting-started.md

examples/python/app.py

@@ -3,7 +3,7 @@ app = Flask(__name__)
 
 @app.route('/')
 def hello_world():
-    return "Hello, World!\n"
+    return "Hello, Universe!\n"
 
 if __name__ == '__main__':
     app.run(host='0.0.0.0', port=8080)