[WIP] docs cleanup

README.md

@@ -95,9 +95,9 @@ that has been thouroughly tested and optimized.
 ## Getting Started
 
 - [How it Works](./docs/how-it-works.md)
-- [Architecture](./docs/README.md#architecture)
-- [See Kube-router in action](./docs/README.md#see-kube-router-in-action)
-- [User Guide](./docs/README.md#user-guide)
+- [Architecture](./docs/architecture.md)
+- [See Kube-router in action](./docs/see-it-in-action.md)
+- [User Guide](./docs/user-guide.md)
 - [Developer Guide](./docs/developing.md)
 
 ## Project status

cmd/kube-router/kube-router_test.go

@@ -32,9 +32,9 @@ func TestMainHelp(t *testing.T) {
 	stderrW.Close()
 	wg.Wait()
 
-	docF, err := os.Open("../../docs/README.md")
+	docF, err := os.Open("../../docs/user-guide.md")
 	if err != nil {
-		t.Fatalf("could not open docs/README.md: %s\n", err)
+		t.Fatalf("could not open docs/user-guide.md: %s\n", err)
 	}
 	docBuf := bytes.NewBuffer(nil)
 	docBuf.ReadFrom(docF)

docs/architecture.md

@@ -0,0 +1,29 @@
+# Architecture
+
+Kube-router is built around concept of watchers and controllers. Watchers use Kubernetes watch API to get notification on events related to create, update, delete of Kubernetes objects. Each watcher gets notification related to a particular API object. On receiving an event from API server, watcher broadcasts events. Controller registers to get event updates from the watchers and act up on the events.
+
+Kube-router consists of 3 core controllers and multiple watchers as depicted in below diagram.
+
+![Arch](./img/kube-router-arch.png)
+
+Each of the [controller](https://github.com/cloudnativelabs/kube-router/tree/master/app/controllers) follows below structure
+
+```
+func Run() {
+    for {
+        Sync() // control loop that runs for ever and perfom sync at periodic interval
+    }
+}
+
+func OnUpdate() {
+    Sync() // on receiving update of a watched API object (namespace, node, pod, network policy etc)
+}
+
+Sync() {
+    //re-concile any state changes
+}
+
+Cleanup() {
+    // cleanup any changes (to iptables, ipvs, network etc) done to the system
+}
+```

docs/introduction.md

@@ -0,0 +1,29 @@
+# Introduction
+
+Welcome to the introduction guide to Kube-router! This guide is the best place to start with Kube-router. We cover what Kube-router is, what problems it can solve, how it compares to existing software, and how you can get started using it. If you are familiar with the basics of Kube-router, head over to the next sections that provide a more detailed reference of available features.
+
+## What is Kube-router
+
+If you are not familiar with Kubernetes networking model it is recommended to familiarize with Kubernetes [networking model](https://kubernetes.io/docs/concepts/cluster-administration/networking/#kubernetes-model). So essentially Kubernetes expects:
+
+- all containers can communicate with all other containers without NAT
+- all nodes can communicate with all containers (and vice-versa) without NAT
+- the IP that a container sees itself as is the same IP that others see it as
+
+Kubernetes only prescribes the requirements for the networking model but does not provide any default implementation. For a functional Kubernetes cluster one has to deploy what is called as CNI or pod networking solution that provides above functionality.
+
+Any non-trivial containerized application will end up running multiple pods running different services. [Service](https://kubernetes.io/docs/concepts/services-networking/service/) abstraction in Kubernetes is an essential building block that helps in service discovery and load balancing. A layer-4 service proxy must be deployed to Kubernetes cluster that provides the load-balancing for the services exposed by the pods.
+
+Once you have pod-to-pod networking established and have a service proxy that provides load-balancing, you need a way to secure your pods. Kubernetes [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) provides a specfication on how to secure pods. You need to deploy a solution that implements network policy specification and provides security to your pods.
+
+Kube-router is a turnkey solution for Kubernetes networking that provides all the above essential functionality in one single elegant package.
+
+## Why Kube-router
+
+Network is hard. You have multiple Kubernetes networking solutions that provide pod networking or network policy etc. But when you deploy indiviudal solution for each functionality you end up with lot of moving parts making it difficult to operate and troubleshoot.
+
+Kube-router is a lean yet powerful all-in-one alternative to several network components used in typical Kubernetes clusters. All this from a single DaemonSet/Binary. It doesn't get any easier. 
+
+Kube-router also uses best of the solution for maximum performance. Kube-router uses IPVS/LVS for service proxy and provides direct routing between the nodes.
+
+Kube-router also provides very unique and advanced functionalities like DSR (Direct Server Return), ECMP based network load balancing etc

docs/see-it-in-action.md

@@ -1,4 +1,41 @@
-## See it in action
+# See Kube-router in action
 
-<a href="https://asciinema.org/a/118056" target="_blank"><img src="https://asciinema.org/a/118056.png" /></a>
+## Network Services Controller
 
+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 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
+
+[![asciicast](https://asciinema.org/a/120312.png)](https://asciinema.org/a/120312)
+
+Features:
+- round robin load balancing
+- client IP based session persistence
+- source IP is preserved if service controller is used in conjuction with network routes controller (kube-router with --run-router flag)
+- option to explicitly masquerade (SNAT) with --masquerade-all flag
+
+## Network Policy Controller
+
+Network policy controller is responsible for reading the namespace, network policy and pods information from Kubernetes API server and configure iptables accordingly to provide ingress filter to the pods.
+
+Kube-router supports the networking.k8s.io/NetworkPolicy API or network policy V1/GA
+[semantics](https://github.com/kubernetes/kubernetes/pull/39164#issue-197243974) and also network policy beta semantics.
+
+Please read blog for design details of Network Policy controller
+https://cloudnativelabs.github.io/post/2017-05-1-kube-network-policies/
+
+Demo of Kube-router's iptables based implementaton of network policies
+
+[![asciicast](https://asciinema.org/a/120735.png)](https://asciinema.org/a/120735)
+
+## Network Routes Controller
+
+Network routes controller is responsible for reading pod CIDR allocated by controller manager to the node, and advertises the routes to the rest of the nodes in the cluster (BGP peers). Use of BGP is transperent to user for basic pod-to-pod networking.
+
+[![asciicast](https://asciinema.org/a/120885.png)](https://asciinema.org/a/120885)
+
+However BGP can be leveraged to other use cases like advertising the cluster ip, routable pod ip etc. Only in such use-cases understanding of BGP and configuration is required. Please see below demo how kube-router advertises cluster IP and pod cidrs to external BGP router
+[![asciicast](https://asciinema.org/a/121635.png)](https://asciinema.org/a/121635)