Merge pull request #184 from heptio/beta1-docs

Docs refresh for Contour 0.6-beta.1. Fixes #171

README.md

@@ -37,11 +37,6 @@ Documentation for all the Gimbal components can be found in the [docs directory]
 * Upstream Kubernetes Pods and OpenStack VMs must be routable from the Gimbal load balancing cluster.
   * Support is not available for Kubernetes clusters with overlay networks.
   * We are looking for community feedback on design requirements for a solution. A possible option is one GRE tunnel per upstream cluster. [Feedback welcome here](https://github.com/heptio/gimbal/issues/39)!
-* The Kubernetes Ingress API is limited and insecure.
-  * Provides only one backend per route.
-  * Anyone can modify route rules for a domain.
-  * More complex load balancing features like weighting and strategy are not supported.
-  * Gimbal & Contour will provide a solution with a [new IngressRoute CRD](https://github.com/heptio/contour/blob/master/design/ingressroute-design.md).
 
 ## Troubleshooting
 

docs/README.md

@@ -21,7 +21,7 @@ These guides describe how the components of Gimbal function and how they interac
 
 ## User Topics
 
-- [Route Specification](route.md)
+- [IngressRoute Management](route.md)
 - [Dashboards / Monitoring / Alerting](monitoring.md)
 
 ## Data Flow

docs/route.md

@@ -1,30 +1,50 @@
 # Route Specification
 
-The core of Gimbal is Routes, which allow traffic into one or more applications. This section will discuss how to utilize Kubernetes `Ingress` objects to create these routes. 
+The core of Gimbal is IngressRoutes, which allow traffic to be routed into one or more applications. This section will discuss how to utilize [Contour IngressRoute](https://github.com/heptio/contour/blob/master/docs/ingressroute.md) objects to create these definitions.
 
 Before beginning it is important to understand how service discovery functions within Gimbal. The Discoverer components should be deployed per upstream cluster. Once synchronized, services will show up in your team namespace with the cluster name appended.
 
-For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `node02`, once synchronized the service in the Gimbal cluster would be named `s1-node02`. 
+For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `cluster1`, once synchronized, the service in the Gimbal cluster would be named `cluster1-s1` and it would be in the `team1` namespace.
 
 ## Basic Route
 
-Following is a basic route which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`. 
+Following is a basic IngressRoute which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`.
 
 ```sh
-apiVersion: extensions/v1beta1
-kind: Ingress
+apiVersion: contour.heptio.com/v1beta1
+kind: IngressRoute
 metadata:
   name: test
 spec:
-  rules:
-  - host: foo.bar.com
-    http:
-      paths:
-      - backend:
-          serviceName: s1-node02
-          servicePort: 80
+  virtualhost:
+    fqdn: foo.bar.com
+  routes:
+    - match: /
+      services:
+        - name: cluster1-service1
+          port: 80
 ```
 
+## IngressRoute Features
+
+The IngressRoute API provides a number of [enhancements](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#key-ingressroute-benefits) over Kubernetes Ingress:
+
+* Weight shifting
+* Multiple services per route
+* Load balancing strategies
+* Multi-team support
+
+## IngressRoute Delegation
+
+Gimbal's multi-team support is enabled through Contour's [IngressRoute Delegation](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#ingressroute-delegation).
+
+### Restricted root namespaces
+
+Contour has an [enforcing mode](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#restricted-root-namespaces) which accepts a list of namespaces where root IngressRoutes are valid.
+Only users permitted to operate in those namespaces can therefore create IngressRoutes with the `virtualhost` field.
+
+This restricted mode is enabled in Contour by specifying a command line flag, `--ingressroute-root-namespaces`, which will restrict Contour to only searching the defined namespaces for root IngressRoutes.
+
 ## Additional Information
 
-More information regarding Ingress can be found here: [https://kubernetes.io/docs/concepts/services-networking/ingress/](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+More information regarding IngressRoutes can be found in the [Contour Documentation](https://github.com/heptio/contour/blob/master/docs/ingressroute.md)

docs/teams.md

@@ -1,6 +1,8 @@
 # Teams with Gimbal
 
-A key feature of Gimbal is team management. Teams should be able to configure and define their own Ingress resources within the Gimbal cluster without requiring an administrator to assist. To enable this, users should be allowed access only to specified namespaces in the Gimbal cluster. Within their respective namespaces, team members should be granted specific authorization to create Ingress routes and to view Services and Endpoints. 
+A key feature of Gimbal is team management. Teams should be able to configure and define their own IngressRoute resources within the Gimbal cluster without requiring an administrator to assist. To enable this, users should be allowed access only to specified namespaces in the Gimbal cluster. Within their respective namespaces, team members should be granted specific authorization to create IngressRoutes and to view Services and Endpoints.
+
+Cluster administrators can [delegate](route.md) specific VirtualHosts (and/or paths) to team namespaces.  Paired with a locked-dwn RBAC policy, Gimbal provides a secure multi-team ingress solution.
 
 ## RBAC rules 
 
@@ -29,4 +31,10 @@ rules:
   - ingresses
   verbs:
   - "*"
+- apiGroups:
+  - contour.heptio.com
+  resources:
+  - ingressroutes
+  verbs:
+  - "*"
 ```