Merge pull request openshift#502 from bfallonf/sticky_sessions

Edits after sticky sessions PR

Author: adellape

architecture/core_objects/routing.adoc

@@ -20,26 +20,27 @@ protocols:
 - WebSockets
 - TLS with SNI
 
-NOTE: WebSocket traffic uses the same route conventions and supports the same
+[NOTE]
+WebSocket traffic uses the same route conventions and supports the same
 TLS termination types as other traffic.
 
 The router uses the service selector to watch the endpoints that support the
 service, bypassing its logic and replacing it with the router's own. Routers
-subscribe to a configuration and automatically update themselves with any
-changes. Router may be containerized or virtual, converting any changes to API
-calls to another system, such as *F5*.
+subscribe to a configuration and automatically update themselves when the
+configuration changes. A router may be containerized or virtual, converting any
+changes to API calls to another system, such as *F5*.
 
 Other capabilities exist to load-balance a service within a cluster. These
 services are exposed via a configurable link relation between different
 services, and ensure a set of services can be available.
 link:../../dev_guide/deployments.html[Deployments] can use these services as
 local proxies for each host, or reuse the shared routing infrastructure.
 
-As an OpenShift administrator, you can configure routers in your instance. This
-allows developers to then set the route types for their projects.
+An OpenShift administrator can configure routers in an OpenShift instance.
+Developers can then set the route types for their projects.
 
 == Route Types
-Routes can be either secure or unsecure. Secure routes provide the ability to
+Routes can be either secure or unsecured. Secure routes provide the ability to
 use different types of TLS termination to serve certificates to the client.
 Routers support link:#edge-termination[edge],
 link:#passthrough-termination[passthrough], and
@@ -48,7 +49,7 @@ link:#re-encryption-termination[re-encryption] termination.
 To create a secure route, specify the TLS termination of the route in a JSON
 file.
 
-.An Unsecure Route
+.An Unsecured Route
 ====
 
 ----
@@ -96,7 +97,7 @@ file.
 ----
 ====
 
-.An Unsecure Route with a Path:
+.An Unsecured Route with a Path:
 ====
 
 ----
@@ -119,10 +120,16 @@ file.
 
 ====
 
-Unsecure routes are likely faster to set up, as they are the default configuration, but secure routes offer greater security for information to remain private.
+Unsecured routes are can be faster to set up, as they are the default
+configuration, but secure routes offer greater security for information to
+remain private.
 
-== Path Based Routes
-Path based routes specify a path component that can be compared against a URL. This implies that the traffic for the route is HTTP based. Routers should match routes based on the most specific path to the least. However, this depends on your implementation. The following table shows example routes and their accessibility:
+== Path-Based Routes
+Path-based routes specify a path component that can be compared against a URL,
+implying that the traffic for the route is HTTP based. Routers should match
+routes based on the most specific path to the least. However, this depends on
+your implementation. The following table shows example routes and their
+accessibility:
 
 ////
 *  For a route with \_www.example.com/test_:
@@ -155,23 +162,24 @@ Path based routes specify a path component that can be compared against a URL. T
 |===
 
 == Securing Routes
-You can create a secure route to your pods by specifying the TLS termination of
-the route and, optionally, providing certificates.
+Create a secure route to your pods by specifying the TLS termination of the
+route and, optionally, providing certificates.
 
-NOTE: Currently, TLS termination in OpenShift Beta relies on SNI for serving
+[NOTE]
+Currently, TLS termination in OpenShift Beta relies on SNI for serving
 custom certificates. Any non-SNI traffic received on port 443 has TLS
 termination with a generic certificate. In the future, the ability to create
 custom front ends within the router will allow all traffic to serve custom
 certificates.
 
-By default, OpenShift routes are unsecure, but can be set to any of the
+By default, OpenShift routes are unsecured, but can be set to any of the
 following three types of secure TLS termination.
 
 [[edge-termination]]
 *Edge Termination*
 
 With edge termination, TLS termination occurs prior to traffic reaching its
-destination. TLS certificates are served by the front end of the router.
+destination. TLS certificates are served by the front-end of the router.
 
 You can configure edge termination on your route by specifying the following:
 
@@ -299,49 +307,50 @@ link:#special-notes[special notes] below.
 [[wildcard-certificates]]
 *Wildcard Certificates*
 
-Based on the implementation, you may be able to use a default certificate. Default certificates
-are useful for implementing a wildcard certificate for the router.  For example, if you have
-many routes that end in example.com you may wish to install a router with a wild card
-certificate for `*.example.com`.
+Depending on your implementation, you can use a default certificate. Default
+certificates are useful for implementing a wildcard certificate for the router.
+For example, if you have many routes that end in `example.com` you may wish to
+install a router with a wildcard certificate for `*.example.com`.
 
-To provide the default certificate to the router you must specify it in the create command with
-the default-cert option. The certificate should be a concatenated file of the key, certificate,
-and any CA certificates that are required by the browser. The certificate should be in a
-form acceptable by the underlying router implementation. In the case of HAProxy it should be a
-PEM based certificate.
-
-****
-`oadm router --credentials="$KUBECONFIG" --default-cert=/full/path/to/certificate.pem`
-****
+To provide the default certificate to the router you must specify it in the
+create command with the `--default-cert` option. The certificate should be a
+concatenated file of the key, certificate, and any CA certificates that are
+required by the browser. The certificate must be in a form acceptable by the
+underlying router implementation. In the case of HAProxy it should be a
+PEM-based certificate.
 
-For HAProxy, if a default certificate is provided, it will load it first. The certificate that
-is loaded first will be presented to any route that matches the CN on the certificate and
-any route that is secure but does not match any configured certificates. For example, if
-the default certificate is for `\*.example.com` and a secure route for `www.foo.com` is created
-with no certificates the route will still be written and the router will serve the `*.example.com`
-certficiate. This may result in a browser warning for users since the CN on the certificate
-does not match the url.
+----
+$ oadm router --credentials="$KUBECONFIG" --default-cert=/full/path/to/certificate.pem
+----
 
-If no default certificate is supplied, the HAProxy router will default to a generic, expired
+For HAProxy, if a default certificate is provided, it will be loaded first. The
+certificate that is loaded first is presented to any route that matches the CN
+on the certificate and any route that is secure but does not match any
+configured certificates. For example, if the default certificate is for
+`\*.example.com` and a secure route for `www.foo.com` is created with no
+certificates the route will still be written and the router will serve the
+`*.example.com` certficiate. This may result in a browser warning for users
+since the CN on the certificate does not match the url. If no default
+certificate is supplied, the HAProxy router will default to a generic, expired
 certificate that is provided in the base image.
 
 [[special-notes]]
 *Special Notes About Secure Routes*
 
 Currently, password protected key files are not supported. HAProxy prompts you
 for a password upon starting and does not have a way to automate this process.
-To remove a passphrase from a keyfile, you can run:
+To remove a passphrase from a keyfile, run:
 
-****
-`# openssl rsa -in _<passwordProtectedKey.key>_ -out _<new.key>_`
-****
+----
+# openssl rsa -in <passwordProtectedKey.key> -out <new.key>
+----
 
-When creating a secure route, you must include your certificate files as a
-single line of text. Replace the existing line breaks with:
+When creating a secure route, include your certificate files as a single line of
+text. Replace the existing line breaks with:
 
-****
-`\n`
-****
+----
+\n
+----
 
 == Routers
 A template router provides certain infrastructure information to the underlying
@@ -353,10 +362,10 @@ router implementation, such as:
 template.
 - Calling a reload script.
 
-Router plug-ins assume they can bind to host ports 80 and 443. This is to allow
-external traffic to route to the host and subsequently through the router.
-Routers also assume that networking is configured such that it can access all
-pods in the cluster.
+Router plug-ins assume they can bind to host ports 80 and 443 to allow external
+traffic to route to the host and subsequently through the router. Routers also
+assume that networking is configured such that it can access all pods in the
+cluster.
 
 At the time of writing, a template router is the single type of router plug-in
 available in OpenShift.
@@ -370,31 +379,29 @@ repository to run an HAProxy instance alongside the template router plug-in. To
 test routes, an install command is provided.
 
 
-Check the default router ("router"):
-
-****
-$ `oadm router --dry-run`
-****
+To check the default router (named *router*):
 
-See what the router would look like if created:
+----
+$ oadm router --dry-run
+----
 
-****
-$ `oadm router -o json`
-****
+To view what the router would look like if created:
 
-Create a router if it does not exist:
+----
+$ oadm router -o json
+----
 
-****
-$ `oadm router router-west --replicas=2 --credentials="$KUBECONFIG"`
-****
+To create a router if it does not exist:
 
-Use a different router image and see the router configuration:
+----
+$ oadm router router-west --replicas=2 --credentials="$KUBECONFIG"
+----
 
-****
-$ `oadm router region-west -o yaml --images=myrepo/somerouter:mytag`
-****
+To use a different router image and view the router configuration:
 
-NOTE: This command is currently being actively developed. It is intended to simplify the tasks of setting up routers in a new installation.
+----
+$ oadm router region-west -o yaml --images=myrepo/somerouter:mytag
+----
 
 The following diagram illustrates how data flows from the master through the
 plug-in and finally into an HAProxy configuration:
@@ -404,13 +411,15 @@ image:router_model.png[HAProxy Router Data Flow]
 
 *Sticky Sessions*
 
-Implementing sticky sessions is up to the underlying router configuration.  The default HAProxy
-template implements sticky sessions using the `balance source` directive which balances based
-on the source IP.  In addition, the template router plugin will provide the service name and
-namespace to the underlying implementation.  This can be used for more advanced configuration
-such as implementing stick-tables that synchronize between a set of peers. For details on the
-implementation you may inspect the `haproxy-config.template` located in the `/var/lib/haproxy/conf`
-directory of your router container.
+Sticky sessions are implemented by the underlying router configuration. The
+default
+link:https://github.com/openshift/origin/blob/3dc5a6e7416a9a6f2270cc236b26be7abb491ab0/images/router/haproxy/conf/haproxy-config.template[HAProxy
+template] in the `/var/lib/haproxy/conf` directory of the router container
+configures sticky sessions using the `balance source` directive, which balances
+based on the source IP. In addition, the template router plug-in provides the
+service name and namespace to the underlying implementation. This can be used
+for more advanced configurations, such as implementing stick-tables to
+synchronize peers.
 
 ////
 == Highly-available Routers