feat(ingress): Experimental Native Ingress

Adding documentation changes for Kubernetes ingress support.

Non breaking change, as	  users must opt-in to the feature.

charts/workflow/values.yaml

@@ -51,6 +51,16 @@ global:
   host_port: 5555
   # Prefix for the imagepull secret created when using private registry
   secret_prefix: "private-registry"
+  # The public resolvable hostname to build your cluster with.
+  #
+  # This will be the hostname that is used to build endpoints such as "deis.$HOSTNAME"
+  hostname: ""
+  # Experimental feature to toggle using kubernetes ingress instead of the Deis router.
+  #
+  # Valid values are:
+  # - true: The Deis router will NOT be deployed. Inherently workflow will not be usable until a Kubernetes ingress controller is installed.
+  # - false: The default mode, and the default behavior of Deis workflow.
+  experimental_native_ingress: false
 
 
 s3:

mkdocs.yml

@@ -37,6 +37,7 @@ pages:
     - Configuring Postgres: installing-workflow/configuring-postgres.md
     - Configuring the Registry: installing-workflow/configuring-registry.md
     - Chart Provenance: installing-workflow/chart-provenance.md
+    - Experimental Native Ingress: installing-workflow/experimental-native-ingress.md
   - Users:
     - Command Line Interface: users/cli.md
     - Users and Registration: users/registration.md

src/installing-workflow/experimental-native-ingress.md

@@ -0,0 +1,80 @@
+# Experimental Native Ingress
+
+## Install Deis Workflow (With experimental native ingress support)
+
+Now that Helm is installed and the repository has been added, install Workflow with a native ingress by running:
+
+```
+$ helm install deis/workflow --namespace deis --set experimental_native_ingress=true,global.hostname="deis.com"
+```
+
+Where `global.hostname` is a **required** parameter that is traditionally not required for Workflow. In this example we are using `deis.com` for `$hostname`.
+
+
+
+Helm will install a variety of Kubernetes resources in the `deis` namespace.
+Wait for the pods that Helm launched to be ready. Monitor their status by running:
+
+```
+$ kubectl --namespace=deis get pods
+```
+
+You should also notice that a Kubernetes ingress has been installed on your cluster. You can view it by running:
+
+```
+$ kubectl get ingress --namespace deis
+```
+
+
+Depending on the order in which the Workflow components initialize, some pods may restart. This is common during the
+installation: if a component's dependencies are not yet available, that component will exit and Kubernetes will
+automatically restart it.
+
+Here, it can be seen that the controller, builder and registry all took a few loops before they were able to start:
+
+```
+$ kubectl --namespace=deis get pods
+NAME                          READY     STATUS    RESTARTS   AGE
+deis-builder-hy3xv            1/1       Running   5          5m
+deis-controller-g3cu8         1/1       Running   5          5m
+deis-database-rad1o           1/1       Running   0          5m
+deis-logger-fluentd-1v8uk     1/1       Running   0          5m
+deis-logger-fluentd-esm60     1/1       Running   0          5m
+deis-logger-sm8b3             1/1       Running   0          5m
+deis-minio-4ww3t              1/1       Running   0          5m
+deis-registry-asozo           1/1       Running   1          5m
+deis-workflow-manager-68nu6   1/1       Running   0          5m
+```
+
+## Install a Kubernetes Ingress Controller
+
+Now that Workflow has been deployed with the `global.exerpimental_native_ingress` flag set to `true`, we will need a Kubernetes ingress controller in place to begin routing traffic.
+
+Here is an example of how to use [traefik](https://traefik.io/) as an ingress controller for Workflow. Of course, you are welcome to use any controller you wish.
+
+```
+$ helm install stable/traefik --name deis-ingress-001 --namespace kube-system
+```
+
+## Configure DNS
+
+The experimental ingress feature requires a user to set up a hostname, and assumes the `deis.$host` convention.
+
+We need to point the `deis.$host` record to the public IP address of your ingress controller. You can get the public IP using the following command.
+
+```
+$ kubectl get svc deis-ingress-001 --namespace kube-system
+NAME               CLUSTER-IP      EXTERNAL-IP       PORT(S)                      AGE
+deis-ingress-001   10.23.253.220   104.154.159.184   80:30231/TCP,443:32264/TCP   19m
+```
+
+If we were using `deis.com` as a hostname we would need to create the following A DNS record.
+
+| Name              | Type          | Value           |
+| ----------------- |:-------------:| ---------------:|
+| deis.deis.com     | A             | 104.154.159.184 |
+
+
+Once all of the pods are in the `READY` state, and `deis.$host` resolves to the external IP found above Workflow is up an running!
+
+After installing Workflow, [register a user and deploy an application](../quickstart/deploy-an-app.md).

src/installing-workflow/index.md

@@ -33,6 +33,10 @@ More rigorous installations would benefit from using outside sources for the fol
 * [Redis](../managing-workflow/platform-logging.md#configuring-off-cluster-redis) - Such as AWS Elasticache
 * [InfluxDB](../managing-workflow/platform-monitoring.md#configuring-off-cluster-influxdb) and [Grafana](../managing-workflow/platform-monitoring.md#off-cluster-grafana)
 
+#### (Experimental) Kubernetes Native Ingress
+
+Workflow now offers [experimental native ingress](experimental-native-ingress.md) that will allow users to take advantage of native Kubernetes ingress with their cluster. Users will be able to use and define any compatible Kubernetes ingress controller. Feel free to start following along with the [experimental native ingress](experimental-native-ingress.md) guide now.
+
 ## Add the Deis Chart Repository
 
 The Deis Chart Repository contains everything needed to install Deis Workflow onto a Kubernetes cluster, with a single `helm install deis/workflow --namespace deis` command.

src/quickstart/deploy-an-app.md

@@ -1,26 +1,46 @@
-## Register an Admin User
+## Determine your host and hostname values
 
-The first user to register against Deis Workflow will automatically be given administrative privileges.
+For the rest of this example we will refer to a special variables called `$hostname`. Please choose one of the two methods for building your `$hostname`.
+
+#### Option 1: Standard Installation 
 
-If you installed Deis on GKE or AWS, Deis automatically creates a load balancer for the cluster. To get the IP of this load balancer, run `kubectl --namespace=deis describe svc deis-router`.
+For a standard installation you can build the hostname using public IP address and a wildcard DNS solution. Instead of setting up DNS records, this example will use `nip.io`. 
+
+If your router IP is `1.1.1.1`, its `$hostname` will be `1.1.1.1.nip.io`. You can find your IP address by running:
+
+```
+kubectl --namespace=deis describe svc deis-router
+```
 
 If you do not have an load balancer IP, the router automatically forwards traffic from a kubernetes node to the router. In this case, use the IP of a kubernetes node and the node
 port that routes to port 80 on the controller.
 
-Deis requires a wildcard DNS record to dynamically map app names to the router. Instead of setting up DNS records, this example will use `nip.io`. If your router IP is `1.1.1.1`, its url will be `1.1.1.1.nip.io`. The URL of the controller component will be `deis.1.1.1.1.nip.io`.
+Deis requires a wildcard DNS record to dynamically map app names to the router.
+
+**$hostname**: 1.1.1.1.nip.io
+
+#### Option 2: Experimental Native Ingress Installation
+
+In this example, the user should already have DNS set up pointing to their known host. The `$hostname` value can be build by appending `deis.` to the value set in `global.exerpimental_native_ingress`.
 
-Use the controller url to register a user in the cluster.
+**$hostname**: deis.com
+
+## Register an Admin User
+
+The first user to register against Deis Workflow will automatically be given administrative privileges.
+
+Use the controller `$hostname` to register a user in the cluster.
 
 ```
-$ deis register http://deis.104.197.125.75.nip.io
+$ deis register http://$hostname
 username: admin
 password:
 password (confirm):
 email: [email protected]
 Registered admin
 Logged in as admin
 $ deis whoami
-You are admin at http://deis.104.197.125.75.nip.io
+You are admin at http://$hostname
 ```
 
 You have now registered your first user and you are ready to deploy an application.
@@ -50,10 +70,12 @@ Let's use the CLI to tell the platform to deploy an application and then use cur
 ```
 $ deis pull deis/example-go -a proper-barbecue
 Creating build... done
-$ curl http://proper-barbecue.104.197.125.75.nip.io
+$ curl http://proper-barbecue.$hostname
 Powered by Deis
 ```
 
+
+
 !!! note
         If you see a 404 error, make sure you specified your application name with `-a <appname>`!