From 2269ff124202ae46e5164bea0065b67bc1c867e3 Mon Sep 17 00:00:00 2001
From: Alec <ahothan@cisco.com>
Date: Fri, 3 Dec 2021 09:48:46 -0800
Subject: [PATCH] docs: address documentation gap when running telegraf in k8s
 (#10215)

---
 plugins/inputs/prometheus/README.md | 40 +++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/plugins/inputs/prometheus/README.md b/plugins/inputs/prometheus/README.md
index 6b94e4be8bd92..74f49a2649c83 100644
--- a/plugins/inputs/prometheus/README.md
+++ b/plugins/inputs/prometheus/README.md
@@ -135,6 +135,46 @@ env:
 
 If using node level scrape scope, `pod_scrape_interval` specifies how often (in seconds) the pod list for scraping should updated. If not specified, the default is 60 seconds.
 
+The pod running telegraf will need to have the proper rbac configuration in order to be allowed to call the k8s api to discover and watch pods in the cluster.
+A typical configuration will create a service account, a cluster role with the appropriate rules and a cluster role binding to tie the cluster role to the service account.
+Example of configuration for cluster level discovery:
+
+```yaml
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: telegraf-k8s-role-{{.Release.Name}}
+rules:
+- apiGroups: [""]
+  resources:
+  - nodes
+  - nodes/proxy
+  - services
+  - endpoints
+  - pods
+  verbs: ["get", "list", "watch"]
+---
+# Rolebinding for namespace to cluster-admin
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: telegraf-k8s-role-{{.Release.Name}}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: telegraf-k8s-role-{{.Release.Name}}
+subjects:
+- kind: ServiceAccount
+  name: telegraf-k8s-{{ .Release.Name }}
+  namespace: {{ .Release.Namespace }}
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: telegraf-k8s-{{ .Release.Name }}
+```
+
 ### Consul Service Discovery
 
 Enabling this option and configuring consul `agent` url will allow the plugin to query