Add clusterRole note for apiserver (elastic#19328)

deploy/kubernetes/metricbeat-kubernetes.yaml

@@ -239,6 +239,14 @@ data:
       period: 10s
       host: ${NODE_NAME}
       hosts: ["kube-state-metrics:8080"]
+    #- module: kubernetes
+    #  metricsets:
+    #    - apiserver
+    #  hosts: ["https://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT}"]
+    #  bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+    #  ssl.certificate_authorities:
+    #    - /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+    #  period: 30s
 ---
 # Deploy singleton instance in the whole cluster for some unique data sources, like kube-state-metrics
 apiVersion: apps/v1
@@ -354,6 +362,10 @@ rules:
   - nodes/stats
   verbs:
   - get
+- nonResourceURLs:
+  - "/metrics"
+  verbs:
+  - get
 ---
 apiVersion: v1
 kind: ServiceAccount

deploy/kubernetes/metricbeat/metricbeat-deployment-configmap.yaml

@@ -48,3 +48,11 @@ data:
       period: 10s
       host: ${NODE_NAME}
       hosts: ["kube-state-metrics:8080"]
+    #- module: kubernetes
+    #  metricsets:
+    #    - apiserver
+    #  hosts: ["https://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT}"]
+    #  bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+    #  ssl.certificate_authorities:
+    #    - /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+    #  period: 30s

deploy/kubernetes/metricbeat/metricbeat-role.yaml

@@ -29,3 +29,7 @@ rules:
   - nodes/stats
   verbs:
   - get
+- nonResourceURLs:
+  - "/metrics"
+  verbs:
+  - get

metricbeat/docs/modules/kubernetes.asciidoc

@@ -45,6 +45,16 @@ Note: Kube-state-metrics is not deployed by default in Kubernetes. For these cas
 
 The apiserver metricset requires access to the Kubernetes API, which should be easily available in all Kubernetes environments. Depending on the Kubernetes configuration, the API access might require SSL (`https`) and token based authentication.
 
+In order to access the `/metrics` path of the API service, some Kubernetes environments might require the following permission to be added to a ClusterRole.
+
+```yaml
+rules:
+- nonResourceURLs:
+  - /metrics
+  verbs:
+  - get
+```
+
 [float]
 ==== proxy
 

metricbeat/module/kubernetes/_meta/docs.asciidoc

@@ -38,6 +38,16 @@ Note: Kube-state-metrics is not deployed by default in Kubernetes. For these cas
 
 The apiserver metricset requires access to the Kubernetes API, which should be easily available in all Kubernetes environments. Depending on the Kubernetes configuration, the API access might require SSL (`https`) and token based authentication.
 
+In order to access the `/metrics` path of the API service, some Kubernetes environments might require the following permission to be added to a ClusterRole.
+
+```yaml
+rules:
+- nonResourceURLs:
+  - /metrics
+  verbs:
+  - get
+```
+
 [float]
 ==== proxy