Documentation updates (#289)

* updated generic docs with some requirements
added draft for metrics docs
updated readme

* more metrics docs

* finishing touches

* small touch to generic docs

* some more touches

* clarification when this function was added

* enriching the doc with usefull links

* last touch

Author: roffe

Documentation/README.md

@@ -116,8 +116,8 @@ Usage of ./kube-router:
       --kubeconfig string                   Path to kubeconfig file with authorization information (the master location is set by the master flag).
       --masquerade-all                      SNAT all traffic to cluster IP/node port.
       --master string                       The address of the Kubernetes API server (overrides any value in kubeconfig).
-      --metrics-port int                    Prometheus metrics port to use, ( default 8080 )
-      --metrics-path string                 Path to serve Prometheus metrics on, ( default /metrics )
+      --metrics-port int                    Prometheus metrics port to use ( default 8080 )
+      --metrics-path string                 Path to serve Prometheus metrics on ( default /metrics )
       --nodeport-bindon-all-ip              For service of NodePort type create IPVS service that listens on all IP's of the node.
       --nodes-full-mesh                     Each node in the cluster will setup BGP peering with rest of the nodes. (default true)
       --peer-router-asns uintSlice          ASN numbers of the BGP peer to which cluster nodes will advertise cluster ip and node's pod cidr. (default [])
@@ -267,3 +267,6 @@ kubectl annotate service my-service "kube-router.io/service.scheduler=dh"
 ## BGP configuration
 
 [Configuring BGP Peers](bgp.md)
+
+## Metrics
+[Configure metrics gathering](metrics.md)

Documentation/generic.md

@@ -6,6 +6,8 @@ All pod networking [CIDRs](https://en.wikipedia.org/wiki/Classless_Inter-Domain_
 
 ### Configuring the Kubelet
 
+If you choose to run kube-router as daemonset, then both kube-apiserver and kubelet must be run with `--allow-privileged=true` option
+
 Ensure each [Kubelet](https://kubernetes.io/docs/reference/generated/kubelet/) is configured with the following options:
 
     --network-plugin=cni
@@ -19,11 +21,13 @@ _**Note: Switching CNI providers on a running cluster requires re-creating all p
 
 ### Configuring kube-controller-manager
 
-The following options are mandatory for [kube-controller-manager](https://kubernetes.io/docs/reference/generated/kube-controller-manager/):
+If you choose to use kube-router for pod-to-pod network connectivity then [kube-controller-manager](https://kubernetes.io/docs/reference/generated/kube-controller-manager/) need to be configured to allocate pod CIDRs by passing `--allocate-node-cidrs=true` flag and providing a `cluster-cidr` (i.e. by passing --cluster-cidr=10.32.0.0/12 for e.g.)
 
-    --cluster-cidr=${POD_NETWORK} # for example 10.32.0.0/12
-    --service-cluster-ip-range=${SERVICE_IP_RANGE} # for example 10.50.0.0/22
+For example:
 
+    --allocate-node-cidrs=true
+    --cluster-cidr=10.32.0.0/12
+    --service-cluster-ip-range=10.50.0.0/22
 
 ## Running kube-router with everything
 

Documentation/metrics.md

@@ -0,0 +1,38 @@
+# Metrics
+
+## Scraping kube-router metrics with Prometheus
+
+The scope of this document is to describe how to setup the [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) needed for [Prometheus](https://prometheus.io/) to use [Kubernetes SD](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#<kubernetes_sd_config>) to discover & scape kube-router [pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/).
+For help with installing Prometheus please see their [docs](https://prometheus.io/docs/introduction/overview/)
+
+By default kube-router will export Prometheus metrics on port `8080` under the path `/metrics`.
+If running kube-router as [daemonset](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) this port might collide with other applications running on the host network and must be changed.
+
+kube-router 0.1.0-rc2 and upwards supports the following runtime configuration for controlling where to expose the metrics.
+If you are using a older version, metrics path & port is locked to `/metrics` & `8080`.
+
+      --metrics-port int                    Prometheus metrics port to use ( default 8080 )
+      --metrics-path string                 Path to serve Prometheus metrics on ( default /metrics )
+
+By enabling [Kubernetes SD](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#<kubernetes_sd_config>) in Prometheus configuration & adding required annotations it can automaticly discover & scrape kube-router metrics.
+
+## Supported annotations
+
+The following annotations can be set on pods/services to enable automatic SD & scraping
+
+* `prometheus.io/scrape`: Only scrape services that have a value of `true`
+* `prometheus.io/path`: If the metrics path is not `/metrics` override this.
+* `prometheus.io/port`: If the metrics are exposed on a different port to the
+
+They are to be set under `spec.template.metadata`
+
+For example:
+
+    spec:
+      template:
+        metadata:
+          labels:
+            k8s-app: kube-router
+          annotations:
+            prometheus.io/scrape: "true"
+            prometheus.io/port: "8080"