Docs: Reworded, reorganized (#48)

* README: Add link to blog about Network Policies
* More style
[skip ci]

Author: bzub

Documentation/README.md

@@ -12,7 +12,7 @@ Kube-router consists of 3 core controllers and multiple watchers as depicted in
 
 Network services controller is responsible for reading the services and endpoints information from Kubernetes API server and configure IPVS on each cluster node accordingly.
 
-Please read blog for design details and pros and cons compared to iptables based Kube-proxy
+Please our read blog for design details and pros and cons compared to iptables based Kube-proxy
 https://cloudnativelabs.github.io/post/2017-05-10-kube-network-service-proxy/
 
 Demo of Kube-router's IPVS based Kubernetes network service proxy

README.md

@@ -4,121 +4,200 @@ kube-router
 [![Build Status](https://travis-ci.org/cloudnativelabs/kube-router.svg?branch=master)](https://travis-ci.org/cloudnativelabs/kube-router)
 [![Gitter chat](http://badges.gitter.im/kube-router/Lobby.svg)](https://gitter.im/kube-router/Lobby)
 
-Kube-router is a distributed load balancer, firewall and router for Kubernetes. Kube-router can be configured to provide on each cluster node:
+Kube-router is a distributed load balancer, firewall and router for Kubernetes
+clusters. It gives your cluster a unified control plane for features
+that would typically be provided by two or three separate software projects.
 
-- a IPVS/LVS based service proxy on each node for *ClusterIP* and *NodePort* service types, providing service discovery and load balancing
-- an ingress firewall for the pods running on the node as per the defined Kubernetes network policies using iptables and ipset
-- a BGP router to advertise and learn the routes to the pod IP's for cross-node pod-to-pod connectivity
+## Project status
 
-## Why Kube-router
-We have Kube-proxy which provides service proxy and load balancer. We have several addons or solutions like Flannel, Calico, Weave etc to provide cross node pod-to-pod networking. Simillarly there are solutions like Calico that enforce network policies. Then why do we need Kube-router for a similar job? Here is the motivation:
+Project is in alpha stage. We are working towards beta release
+[milestone](https://github.com/cloudnativelabs/kube-router/milestone/2) and are
+activley incorporating users feedback.
 
-- It is challenging to deploy, monitor and troubleshoot multiple solutions at runtime. These independent solution need to work well together. Kube-router aims to provide operational simplicity by combining all the networking functionality that can be provided at the node in to one cohesive solution. Run Kube-router as daemonset, by just running one command ``kubectl create -f kube-router-daemonset.yaml`` you have solution for pod-to-pod networking, service proxy and firewall on each node.
+## Getting Started
 
-- Kube-router is motivated to provide optimized solution for performance. Kube-router uses IPVS for service proxy as compared to iptables by Kube-proxy. Kube-router uses solutions like ipsets to optimize iptables rules matching while providing ingress firewall for the pods. For inter-node pod-to-pod communication, routing rules added by kube-router ensures data path is efficient (one hop for pod-to-pod connectivity) with out overhead of overlays.
+- [User Guide](./Documentation/README.md#user-guide)
+- [Developer Guide](./Documentation/developing.md)
+- [Architecture](./Documentation/README.md#architecture)
 
-- Kube-router builds on standard Linux technologies, so you can verify the configuration and troubleshoot with standard Linux networking tools (ipvsadm, ip route, iptables, ipset, traceroute, tcpdump etc).
+## Primary Features
 
-- Kube-router is a solution purpose built for Kubernetes. So it does not carry the burden of functionality to support other container orchestration and infrastrcutre orchestration platforms. Code base is extremely small for the functionality it provides and easy to hack up and customize.
+*kube-router does it all.*
 
-## See it in action
+With all features enabled, kube-router is a lean yet powerful alternative to
+several software components used in typical Kubernetes clusters. All this from a
+single DaemonSet/Binary. It doesn't get any easier.
 
-<a href="https://asciinema.org/a/118056" target="_blank"><img src="https://asciinema.org/a/118056.png" /></a>
+### Alternative to kube-proxy | `--run-service-proxy`
 
-## Project status
+kube-router uses the Linux kernel's IPVS features to implement its K8s Services
+Proxy. This feature has been requested for some time in kube-proxy, but you can
+have it right now with kube-router.
 
-Project is in alpha stage. We are working towards beta release [milestone](https://github.com/cloudnativelabs/kube-router/milestone/2) and are activley incorporating users feedback.
+Read more about the advantages of IPVS for container load balancing:
+- [Kubernetes network services proxy with IPVS/LVS](https://cloudnativelabs.github.io/post/2017-05-10-kube-network-service-proxy/)
+- [Kernel Load-Balancing for Docker Containers Using IPVS](https://blog.codeship.com/kernel-load-balancing-for-docker-containers-using-ipvs/)
 
-## Support & Feedback
+### Pod Networking | `--run-router`
 
-If you experience any problems please reach us on gitter [community forum](https://gitter.im/kube-router/Lobby) for quick help. Feel free to leave feedback or raise questions at any time by opening an issue [here](https://github.com/cloudnativelabs/kube-router/issues).
+kube-router handles Pod networking efficiently with direct routing thanks to the
+BGP protocol and the GoBGP Go library. It uses the native Kubernetes API to
+maintain distributed pod networking state. That means no dependency on a
+separate datastore to maintain in your cluster.
 
-## Getting Started
+kube-router's elegant design also means there is no dependency on another CNI
+plugin. The
+[official "bridge" plugin](https://github.com/containernetworking/plugins/tree/master/plugins/main/bridge)
+provided by the CNI project is all you need -- and chances are you already have
+it in your CNI binary directory!
 
-Use below guides to get started.
+Read more about the advantages and potential of BGP with Kubernetes:
+- [Kubernetes pod networking and beyond with BGP](https://cloudnativelabs.github.io/post/2017-05-22-kube-pod-networking)
 
-- [Architecture](./Documentation/README.md#architecture)
-- [Users Guide](./Documentation/README.md#user-guide)
-- [Developers Guide](./Documentation/README.md#develope-guide)
+### Network Policy Controller | `--run-firewall`
+
+Enabling Kubernetes [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
+is easy with kube-router -- just add a flag to kube-router. It uses ipsets with
+iptables to ensure your firewall rules have as little performance impact on your
+cluster as possible.
+
+Read more about kube-router's approach to Kubernetes Network Policies:
+- [Enforcing Kubernetes network policies with iptables](https://cloudnativelabs.github.io/post/2017-05-1-kube-network-policies/)
+
+### Advanced BGP Capabilities
+
+If you have other networking devices or SDN systems that talk BGP, kube-router
+will fit in perfectly. From a simple full node-to-node mesh to per-node peering
+configurations, most routing needs can be attained. The configuration is
+Kubernetes native (annotations) just like the rest of kube-router, so use the
+tools you already know! Since kube-router uses GoBGP, you have access to a
+modern BGP API platform as well right out of the box.
+
+For more details please refer to the [BGP documentation](Documentation/bgp.md).
 
-## Contribution
+### Small Footprint
+
+Although it does the work of several of its peers in one binary, kube-router
+does it all with a relatively tiny codebase, partly because IPVS is already
+there on your Kuberneres nodes waiting to help you do amazing things.
+kube-router brings that and GoBGP's modern BGP interface to you in an elegant
+package designed from the ground up for Kubernetes.
+
+### High Performance
+
+A primary motivation for kube-router is performance. The combination of BGP for
+inter-node Pod networking and IPVS for load balanced proxy Services is a perfect
+recipe for high-performance cluster networking at scale. BGP ensures that the
+data path is dynamic and efficient, and IPVS provides in-kernel load balancing
+that has been thouroughly tested and optimized.
+
+## Contributing
+
+We encourage all kinds of contributions, be they documentation, code, fixing
+typos, tests — anything at all. Please read the [contribution guide](./CONTRIBUTING.md).
+
+## Support & Feedback
+
+If you experience any problems please reach us on our gitter
+[community forum](https://gitter.im/kube-router/Lobby)
+for quick help. Feel free to leave feedback or raise questions at any time by
+opening an issue [here](https://github.com/cloudnativelabs/kube-router/issues).
+
+## See it in action
+
+<a href="https://asciinema.org/a/118056" target="_blank"><img src="https://asciinema.org/a/118056.png" /></a>
 
-We encourage all kinds of contributions, be they documentation, code, fixing typos, tests — anything at all. Please
-read the [contribution guide](./CONTRIBUTING.md).
 
 ## Theory of Operation
 
-Kube-router can be run as a agent or a pod (through daemonset) on each node and leverages standard Linux technologies **iptables, ipvs/lvs, ipset, iproute2** 
+Kube-router can be run as an agent or a Pod (via DaemonSet) on each node and
+leverages standard Linux technologies **iptables, ipvs/lvs, ipset, iproute2**
 
-### service proxy and load balancing 
+### Service Proxy And Load Balancing
 
-refer to https://cloudnativelabs.github.io/post/2017-05-10-kube-network-service-proxy/ for the design details and demo
+[Kubernetes network services proxy with IPVS/LVS](https://cloudnativelabs.github.io/post/2017-05-10-kube-network-service-proxy/)
 
-Kube-router uses IPVS/LVS technology built in Linux to provide L4 load balancing. Each of the kubernetes service of **ClusterIP** and **NodePort** type is configured as IPVS virtual service. Each service endpoint is configured as real server to the virtual service.
-Standard **ipvsadm** tool can be used to verify the configuration and monitor the active connections. 
+Kube-router uses IPVS/LVS technology built in Linux to provide L4 load
+balancing. Each **ClusterIP** and **NodePort** Kubernetes Service type is
+configured as an IPVS virtual service. Each Service Endpoint is configured as
+real server to the virtual service.  The standard **ipvsadm** tool can be used
+to verify the configuration and monitor the active connections.
 
-Below is example set of services on kubernetes
+Below is example set of Services on Kubernetes:
 
 ![Kube services](./Documentation/img/svc.jpg)
 
-and the endpoints for the services
+and the Endpoints for the Services:
 
 ![Kube services](./Documentation/img/ep.jpg)
 
-and how they got mapped to the ipvs by kube-router
+and how they got mapped to the IPVS by kube-router:
 
 ![IPVS configuration](./Documentation/img/ipvs1.jpg)
 
-Kube-router watches kubernetes API server to get updates on the services, endpoints and automatically syncs the ipvs
-configuration to reflect desired state of services. Kube-router uses IPVS masquerading mode and uses round robin scheduling
-currently. Source pod IP is preserved so that appropriate network policies can be applied.
+Kube-router watches the Kubernetes API server to get updates on the
+Services/Endpoints and automatically syncs the IPVS configuration to reflect the
+desired state of Services. Kube-router uses IPVS masquerading mode and uses
+round robin scheduling currently. Source pod IP is preserved so that appropriate
+network policies can be applied.
 
-### pod ingress firewall 
+### Pod Ingress Firewall
 
-refer to https://cloudnativelabs.github.io/post/2017-05-1-kube-network-policies/ for the detailed design details
+[Enforcing Kubernetes network policies with iptables](https://cloudnativelabs.github.io/post/2017-05-1-kube-network-policies/)
 
-Kube-router provides implementation of network policies semantics through the use of iptables, ipset and conntrack.
-All the pods in a namespace with 'DefaultDeny' ingress isolation policy has ingress blocked. Only traffic that matches
-whitelist rules specified in the network policies are permitted to reach pod. Following set of iptables rules and 
-chains in the 'filter' table are used to achieve the network policies semantics.
+Kube-router provides an implementation of Kubernetes Network Policies through
+the use of iptables, ipset and conntrack.  All the Pods in a Namespace with
+'DefaultDeny' ingress isolation policy has ingress blocked. Only traffic that
+matches whitelist rules specified in the network policies are permitted to reach
+those Pods. The following set of iptables rules and chains in the 'filter' table
+are used to achieve the Network Policies semantics.
 
-Each pod running on the node, which needs ingress blocked by default is matched in FORWARD and OUTPUT chains of fliter table 
-and send to pod specific firewall chain. Below rules are added to match various cases
+Each Pod running on the Node which needs ingress blocked by default is matched
+in FORWARD and OUTPUT chains of the fliter table and are sent to a pod specific
+firewall chain. Below rules are added to match various cases
 
-- traffic getting switched between the pods on the same node through bridge
-- traffic getting routed between the pods on different nodes
-- traffic originating from a pod and going through the service proxy and getting routed to pod on same node
+- Traffic getting switched between the Pods on the same Node through the local
+  bridge
+- Traffic getting routed between the Pods on different Nodes
+- Traffic originating from a Pod and going through the Service proxy and getting
+  routed to a Pod on the same Node
 
 ![FORWARD/OUTPUT chain](./Documentation/img/forward.png)
 
-Each pod specific firewall chain has default rule to block the traffic. Rules are added to jump traffic to the network policy 
-specific policy chains. Rules cover only policies that apply to the destination pod ip. A rule is added to accept the
-the established traffic to permit the return traffic.
+Each Pod specific firewall chain has default rule to block the traffic. Rules
+are added to jump traffic to the Network Policy specific policy chains. Rules
+cover only policies that apply to the destination pod ip. A rule is added to
+accept the the established traffic to permit the return traffic.
 
 ![Pod firewall chain](./Documentation/img/podfw.png)
 
-Each policy chain has rules expressed through source and destination ipsets. Set of pods matching ingress rule in network policy spec
-forms a source pod ip ipset. set of pods matching pod selector (for destination pods) in the network policy forms
-destination pod ip ipset.
+Each policy chain has rules expressed through source and destination ipsets. Set
+of pods matching ingress rule in network policy spec forms a source Pod ip
+ipset. set of Pods matching pod selector (for destination Pods) in the Network
+Policy forms destination Pod ip ipset.
 
 ![Policy chain](./Documentation/img/policyfw.png)
 
-Finally ipsets are created that are used in forming the rules in the network policy specific chain
+Finally ipsets are created that are used in forming the rules in the Network
+Policy specific chain
 
 ![ipset](./Documentation/img/ipset.jpg)
 
-Kube-router at runtime watches Kubernetes API server for changes in the namespace, network policy and pods and
-dynamically updates iptables and ipset configuration to reflect desired state of ingress firewall for the the pods.
-
-### Pod networking
+Kube-router at runtime watches Kubernetes API server for changes in the
+namespace, network policy and pods and dynamically updates iptables and ipset
+configuration to reflect desired state of ingress firewall for the the pods.
 
-Please see the [blog](https://cloudnativelabs.github.io/post/2017-05-22-kube-pod-networking/) for design details.
+### Pod Networking
 
-Kube-router is expected to run on each node. Subnet of the node is learnt by kube-router from the CNI configuration file on the node or through the node.PodCidr. Each kube-router
-instance on the node acts a BGP router and advertise the pod CIDR assigned to the node. Each node peers with rest of the 
-nodes in the cluster forming full mesh. Learned routes about the pod CIDR from the other nodes (BGP peers) are injected into
-local node routing table. On the data path, inter node pod-to-pod communication is done by routing stack on the node.
+[Kubernetes pod networking and beyond with BGP](https://cloudnativelabs.github.io/post/2017-05-22-kube-pod-networking)
 
+Kube-router is expected to run on each Node. The subnet of the Node is obtained
+from the CNI configuration file on the Node or through the Node.PodCidr. Each
+kube-router instance on the Node acts as a BGP router and advertises the Pod
+CIDR assigned to the Node. Each Node peers with rest of the Nodes in the cluster
+forming full mesh. Learned routes about the Pod CIDR from the other Nodes (BGP
+peers) are injected into local Node routing table. On the data path, inter Node
+Pod-to-Pod communication is done by the routing stack on the Node.
 
 ## TODO
 - ~~convert Kube-router to docker image and run it as daemonset~~