Add cluster role document

assets/docs/troubleshooting/provisioning_flow_chart.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-10-17T06:40:47.179Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36" etag="AmT132Al3Uuuwq-LVecO" version="20.4.0" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="main_chart">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</diagram></mxfile>

docs/overview/component/discoverer.md

@@ -65,3 +65,7 @@ For example, Vald LB Gateway creates the new `discoverer client` with config par
 When the `initContainer` successes, Vald LB Gateway can get the metrics asynchronously according to its set parameters.
 
 <!-- TODO:image -->
+
+### Cluster role configurations
+
+Please refer [here](../../user-guides/cluster-role-binding.md) for more information about the cluster role configuration.

docs/user-guides/cluster-role-binding.md

@@ -0,0 +1,143 @@
+# Cluster Role Configuration
+
+The cluster role contains rules that represent a set of permission to grant access to a specific target depending on the binding rule.
+
+This page describes why we need a cluster role for the Vald cluster and how to configure it.
+
+## What are cluster role and cluster role binding for the Vald cluster?
+
+Vald applies the distributed index system across the Kubernetes cluster depending on the resource usage of the Kubernetes Node, it requires configuration to grant permission to a specific role to retrieve cluster information on Kubernetes.
+
+By default, the cluster role configurations are deployed automatically when using Helm.
+
+The following manifest will be deployed by default.
+
+- [clusterrole.yaml](https://github.com/vdaas/vald/blob/main/k8s/discoverer/clusterrole.yaml)
+- [clusterrolebinding.yaml](https://github.com/vdaas/vald/blob/main/k8s/discoverer/clusterrolebinding.yaml)
+
+These configurations allow the service account `discoverer`, which is for the Vald Discoverer components, to access different resources in the Kubernetes cluster.
+
+This service account allows [Vald Discoverer](../overview/component/discoverer.md) to retrieve Node and Pod resource usage from [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/), and share it to other components in the Vald cluster.
+
+For example, [Vald LB Gateway](../overview/component/lb-gateway.md) will control which Vald Agent to insert based on the Node and Pod resource usage retrieved by Vald Discoverer.
+
+If you are interested, please refer to the [insert data flow](../overview/data-flow.md#insert) for more detail.
+
+## Configuration for Vald Discoverer
+
+As described in the above section, Vald Discoverer requires configuration on cluster role and cluster role binding to retrieve Node and Pod information from the Kubernetes Cluster.
+
+In this section, we will describe how to configure it and how to customize these configurations.
+
+### Cluster role configuration for Vald Discoverer
+
+By looking at the [cluster role configuration](https://github.com/vdaas/vald/blob/main/k8s/discoverer/clusterrole.yaml), the access right of the following resources are granted to the cluster role `discoverer`.
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: discoverer
+...
+rules:
+  - apiGroups:
+      - apps
+    resources:
+      - replicasets
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - ""
+    resources:
+      - nodes
+      - nodes/proxy
+      - services
+      - endpoints
+      - pods
+    verbs:
+      - get
+      - list
+      - watch
+  - nonResourceURLs:
+      - /metrics
+    verbs:
+      - get
+  - apiGroups:
+      - "metrics.k8s.io"
+    resources:
+      - nodes
+      - pods
+    verbs:
+      - get
+      - list
+```
+
+All of these rules are required to retrieve Node and Pod resource usage from [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) and also used to discover new Vald Agent Pods or Nodes created on the cluster.
+
+### Cluster role binding configuration for Vald Discoverer
+
+The cluster role binding configuration binds the cluster role `discoverer` described in the previous section to the service account `vald` according to the [configuration file](https://github.com/vdaas/vald/blob/main/k8s/discoverer/clusterrolebinding.yaml).
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: discoverer
+  ...
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: discoverer
+subjects:
+  - kind: ServiceAccount
+    name: vald
+    namespace: default
+```
+
+When the role binds to the service account, the access right of the role will be granted to the service account.
+In this case, all the access rights of the role `discoverer` will be granted to the service account `vald`.
+
+The service account `vald` is required for [Vald Discoverer](https://github.com/vdaas/vald/blob/main/k8s/discoverer/deployment.yaml#L155) to retrieve the required information to operate the Vald cluster.
+
+For more information about Vald Discoverer, please refer [here](../overview/component/discoverer.md).
+
+## Customize cluster role and cluster role binding configuration on Helm chart for Vald Discoverer
+
+To customize the cluster role configuration on the Helm chart for Vald Discoverer, you may need to change the `discoverer.clusterRole` configuration on the Helm chart file. The cluster role configurations are enabled by default.
+
+```yaml
+  clusterRole:
+    # discoverer.clusterRole.enabled -- creates clusterRole resource
+    enabled: true
+    # discoverer.clusterRole.name -- name of clusterRole
+    name: discoverer
+  clusterRoleBinding:
+    # discoverer.clusterRoleBinding.enabled -- creates clusterRoleBinding resource
+    enabled: true
+    # discoverer.clusterRoleBinding.name -- name of clusterRoleBinding
+    name: discoverer
+  serviceAccount:
+    # discoverer.serviceAccount.enabled -- creates service account
+    enabled: true
+    # discoverer.serviceAccount.name -- name of service account
+    name: vald
+```
+
+Please note that if you disable these configurations, the [Vald Discoverer](../overview/component/discoverer.md) will not work, and the Vald cluster will not be functional.
+
+If you want to modify or disable these configurations, you need to grant the [cluster role configuration](https://github.com/vdaas/vald/blob/main/k8s/discoverer/clusterrole.yaml) and bind it to the Vald Discoverer to retrieve required information to operate the Vald cluster.
+
+## Customize cluster role configuration on Cloud Providers
+
+Please refer to the following guidelines to configure cluster role configuration for your cloud provider, and configure the service account name for Vald Discoverer.
+
+- [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html)
+- [GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control)
+
+For other cloud providers, you may need to find the related document on their official website, or you can enable the cluster role and the cluster role binding configurations on the Helm chart.
+
+## Related Document
+
+- [Vald Discoverer](../overview/component/discoverer.md)