From 94d2fe90eb95f69c6010cdab3762d10d838d217b Mon Sep 17 00:00:00 2001
From: Mukundan Sundararajan <musundar@microsoft.com>
Date: Tue, 18 Aug 2020 12:50:46 -0700
Subject: [PATCH] Change reference spec for the kubernetes events input
 binding.  (#752)

* Change reference spec for the kubernetes events input binding. Add Role ,RoleBinding doc.

* Refactor docs

* Update kubernetes.md
---
 reference/specs/bindings/kubernetes.md | 82 +++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/reference/specs/bindings/kubernetes.md b/reference/specs/bindings/kubernetes.md
index efcac241a..2feaab856 100644
--- a/reference/specs/bindings/kubernetes.md
+++ b/reference/specs/bindings/kubernetes.md
@@ -10,7 +10,85 @@ spec:
   type: bindings.kubernetes
   metadata:
   - name: namespace
-    value: default
+    value: <NAMESPACE>
+  - name: resyncPeriodInSec
+    vale: "<seconds>"
 ```
 
-- `namespace` is the Kubernetes namespace to read events from. Default is `default`.
+- `namespace` (required) is the Kubernetes namespace to read events from.
+- `resyncPeriodInSec` (optional, default `10`) the period of time to refresh event list from Kubernetes API server.
+
+Output received from the binding is of format `bindings.ReadResponse` with the `Data` field populated with the following structure: 
+
+```json
+ {
+   "event": "",
+   "oldVal": {
+     "metadata": {
+       "name": "hello-node.162c2661c524d095",
+       "namespace": "kube-events",
+       "selfLink": "/api/v1/namespaces/kube-events/events/hello-node.162c2661c524d095",
+       ...
+     },
+     "involvedObject": {
+       "kind": "Deployment",
+       "namespace": "kube-events",
+       ...
+     },
+     "reason": "ScalingReplicaSet",
+     "message": "Scaled up replica set hello-node-7bf657c596 to 1",
+     ...
+   },
+   "newVal": {
+     "metadata": { "creationTimestamp": "null" },
+     "involvedObject": {},
+     "source": {},
+     "firstTimestamp": "null",
+     "lastTimestamp": "null",
+     "eventTime": "null",
+     ...
+   }
+ }
+```
+Three different event types are available: 
+- Add : Only the `newVal` field is populated, `oldVal` field is an empty `v1.Event`, `event` is `add`
+- Delete : Only the `oldVal` field is populated, `newVal` field is an empty `v1.Event`, `event` is `delete`
+- Update : Both the `oldVal` and `newVal` fields are populated,  `event` is `update`
+
+## Required permisiions
+
+For consuming `events` from Kubernetes, permissions need to be assigned to a User/Group/ServiceAccount using [RBAC Auth] mechanism of Kubernetes.
+
+### Role
+
+One of the rules need to be of the form as below to give permissions to `get, watch` and `list` `events`. API Groups can be as restrictive as needed.
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  namespace: <NAMESPACE>
+  name: <ROLENAME>
+rules:
+- apiGroups: [""]
+  resources: ["events"]
+  verbs: ["get", "watch", "list"]
+```
+
+### RoleBinding
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: <NAME>
+  namespace: <NAMESPACE> # same as above
+subjects:
+- kind: ServiceAccount
+  name: default # or as need be, can be changed
+  namespace: <NAMESPACE> # same as above
+roleRef:
+  kind: Role
+  name: <ROLENAME> # same as the one above
+  apiGroup: ""
+```