Docs explaining the new ingress-to-route controller

architecture/networking/routes.adoc

@@ -833,3 +833,59 @@ $ oc expose service/<name> --hostname="m.api.openshift.org"
 $ oc expose service/<name> --hostname="kates.net"
 $ oc expose service/<name> --hostname="api.kates.net"
 ----
+
+
+== Support for Kubernetes ingress objects in OpenShift
+
+In an effort to support the Kubernetes method of managing external access to services
+in a cluster an ingress to route controller has been created. This controller watches
+ingress objects and attempts to create one or more routes to satisfy the conditions of
+the ingress object. For example
+
+----
+kind: Ingress
+apiVersion: extensions/v1beta1
+metadata:
+  name: test
+spec:
+  rules:
+  - host: test.com
+     http:
+       paths:
+       - path: /test
+         backend:
+           serviceName: test-1
+           servicePort: 80
+----
+
+would generate
+
+----
+kind: Route
+apiVersion: route.openshift.io/v1
+metadata:
+  name: test-a34th
+  ownerReferences:
+  - apiVersion: extensions/v1beta1
+     kind: Ingress
+     name: test
+     controller: true
+spec:
+  host: test.com
+  path: /test
+  to:
+    name: test-1
+  port:
+     targetPort: 80
+----
+
+The ingress to route controller is responsible for keeping the ingress object and the generated 
+route objects in sync, including giving generated routes permissions on the secrets associated with
+the ingress object. Hostname claims are made by the generated route objects. 
+
+[NOTE]
+====
+In order for a route to be created an ingress object needs to have a host, service, and path. 
+The resulting route objects created have an autogenerated name with the name of the ingress object 
+as a prefix. 
+====