From 47118f27b17fb275eddf2725a4a373939fbce2a1 Mon Sep 17 00:00:00 2001
From: Florian Bacher <florian.bacher@dynatrace.com>
Date: Fri, 11 Oct 2024 10:36:54 +0200
Subject: [PATCH] [chore] add documentation for setting up RBAC for the
 k8sobserver extension (#35597)

#### Description
This PR extends the readme of the k8sobserver by describing how to set
up the required RBAC permissions to observe the related k8s resources

#### Link to tracking issue
Fixes #35595

#### Documentation
Extended the readme

Signed-off-by: Florian Bacher <florian.bacher@dynatrace.com>
---
 extension/observer/k8sobserver/README.md | 167 ++++++++++++++++++++++-
 1 file changed, 166 insertions(+), 1 deletion(-)

diff --git a/extension/observer/k8sobserver/README.md b/extension/observer/k8sobserver/README.md
index 6929cbd799ce..9b3856b042f3 100644
--- a/extension/observer/k8sobserver/README.md
+++ b/extension/observer/k8sobserver/README.md
@@ -75,4 +75,169 @@ All fields are optional.
 | observe_ingresses | bool | `false` | Whether to report observer k8s.ingress endpoints.|  
 
 More complete configuration examples on how to use this observer along with the `receiver_creator`,
-can be found at the [Receiver Creator](../../../receiver/receivercreator/README.md)'s documentation.
\ No newline at end of file
+can be found at the [Receiver Creator](../../../receiver/receivercreator/README.md)'s documentation.
+
+### Setting up RBAC permissions
+
+When using the `serviceAccount` `auth_type`, the service account of the pod running the agent needs to have the required permissions to
+read the K8s resources it should observe (i.e. pods, nodes, services and ingresses).
+Therefore, the service account running the pod needs to have the required `ClusterRole` which grants it the permission to
+read those resources from the Kubernetes API. Below is an example of how to set this up:
+
+1. Create a `ServiceAccount` that the collector should use.
+
+```bash
+<<EOF | kubectl apply -f -
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  labels:
+    app: otelcontribcol
+  name: otelcontribcol
+EOF
+```
+
+2. Create a `ClusterRole`/`ClusterRoleBinding` that grants permission to read pods, nodes, services and ingresses.
+
+Note: If you do not plan to observe all of these resources (e.g. if you are only interested in services) it is recommended to remove
+the resources you do not intend to observe from the configuration below:
+
+```bash
+<<EOF | kubectl apply -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: otelcontribcol
+  labels:
+    app: otelcontribcol
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - nodes
+  - services
+  - pods
+  verbs:
+  - get
+  - list
+  - watch
+- apiGroups: 
+  - "networking.k8s.io"
+  resources:
+  - ingresses
+  verbs:
+  - get
+  - watch
+  - list
+EOF
+```
+
+```bash
+<<EOF | kubectl apply -f -
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: otelcontribcol
+  labels:
+    app: otelcontribcol
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: otelcontribcol
+subjects:
+- kind: ServiceAccount
+  name: otelcontribcol
+  namespace: default
+EOF
+```
+3. Create a ConfigMap containing the configuration for the collector
+
+```bash
+cat <<EOF | kubectl apply -f -
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: otelcontribcol
+  labels:
+    app: otelcontribcol
+data:
+  config.yaml: |
+    extensions:
+      k8s_observer:
+        auth_type: serviceAccount
+        node: ${env:K8S_NODE_NAME}
+        observe_pods: true
+        observe_nodes: true
+        observe_services: true
+        observe_ingresses: true
+    
+    receivers:
+      receiver_creator:
+        watch_observers: [k8s_observer]
+        receivers:
+          redis:
+            rule: type == "port" && pod.name matches "redis"
+            config:
+              password: '`pod.labels["SECRET"]`'
+          kubeletstats:
+            rule: type == "k8s.node"
+            config:
+              auth_type: serviceAccount
+              collection_interval: 10s
+              endpoint: "`endpoint`:`kubelet_endpoint_port`"
+              extra_metadata_labels:
+                - container.id
+              metric_groups:
+                - container
+                - pod
+                - node
+    
+    exporters:
+      otlp:
+        endpoint: <OTLP_ENDPOINT>
+
+    service:
+      pipelines:
+        metrics:
+          receivers: [receiver_creator]
+          exporters: [otlp]
+EOF
+```
+
+4. Create the collector deployment, referring to the service account created earlier
+
+```bash
+<<EOF | kubectl apply -f -
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: otelcontribcol
+  labels:
+    app: otelcontribcol
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: otelcontribcol
+  template:
+    metadata:
+      labels:
+        app: otelcontribcol
+    spec:
+      serviceAccountName: otelcontribcol
+      containers:
+      - name: otelcontribcol
+        # This image is created by running `make docker-otelcontribcol`.
+        # If you are not building the collector locally, specify a published image: `otel/opentelemetry-collector-contrib`
+        image: otelcontribcol:latest
+        args: ["--config", "/etc/config/config.yaml"]
+        volumeMounts:
+        - name: config
+          mountPath: /etc/config
+        imagePullPolicy: IfNotPresent
+      volumes:
+        - name: config
+          configMap:
+            name: otelcontribcol
+EOF
+```
\ No newline at end of file