Merge pull request #782 from mboersma/byo-ingress

feat(ingress): experimental native ingress

Author: mboersma

charts/workflow/values.yaml

@@ -51,6 +51,12 @@ global:
   host_port: 5555
   # Prefix for the imagepull secret created when using private registry
   secret_prefix: "private-registry"
+  # Experimental feature to use Kubernetes ingress instead of Workflow's deis-router.
+  #
+  # Valid values are:
+  # - true: deis-router will not be deployed. Workflow will not be usable until a Kubernetes ingress controller is installed.
+  # - false: deis-router will be deployed (default).
+  experimental_native_ingress: false
 
 
 s3:
@@ -107,6 +113,10 @@ controller:
   # disabled - turns off open registration
   # admin_only - allows for registration by an admin only.
   registration_mode: "admin_only"
+  # The publicly resolvable hostname to build your cluster with.
+  #
+  # This will be the hostname that is used to build endpoints such as "deis.$HOSTNAME"
+  platform_domain: ""
 
 database:
   # The username and password to be used by the on-cluster database.

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,81 @@
+# 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 global.experimental_native_ingress=true,controller.platform_domain=deis.com
+```
+
+Where `controller.platform_domain` is a **required** parameter that is traditionally not required for Workflow that is explained in the next section. 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 several Kubernetes ingresses 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 waiting for minio 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.experimental_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 `*.$host` record to the public IP address of your ingress controller. You can get the public IP using the following command. A wildcard entry is necessary here as apps will use the same rule after they are deployed.
+
+```
+$ 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).
+
+##### Feedback
+
+While this feature is experimental we welcome feedback on the issue. We would like to learn more about use cases, and user experience. Please [open a new issue](https://github.com/deis/workflow/issues/new) for feedback.

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) to take advantage of native Kubernetes routing. Any compatible Kubernetes ingress controller can be used in place of Workflow's nginx-based deis-router. Follow [this guide](experimental-native-ingress.md) to enable experimental native ingress.
+
 ## 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,44 @@
-## 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`.
 
-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`.
+#### Option 1: Standard Installation 
+
+For a standard installation that includes deis-router, you can calculate the hostname value using its public IP address and a wildcard DNS record.
+
+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 workflow requires a wildcard DNS record to dynamically map app names to the router.
+
+#### Option 2: Experimental Native Ingress Installation
 
-Use the controller url to register a user in the cluster.
+In this example, the user should already have DNS set up pointing to their known host. The `$hostname` value can be calculated by prepending `deis.` to the value set in `controller.platform_domain`.
+
+**$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: jhansen@deis.com
 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,7 +68,7 @@ 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
 ```