Clarify RBAC in TargetAllocator readme. #2734

Author: avillela

cmd/otel-allocator/README.md

@@ -118,14 +118,32 @@ OpenTelemetry Collector Operator-specific config.
 
 Upstream documentation here: [PrometheusReceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver#opentelemetry-operator)
 
-The TargetAllocator service is named based on the OpenTelemetryCollector CR name. `collector_id` should be unique per
+The TargetAllocator service is named based on the `OpenTelemetryCollector` CR name. For example, if your Collector CR name is `my-collector`, then the TargetAllocator `service` and `deployment` will each be named `my-collector-targetallocator`, and the `pod` will be named `my-collector-targetallocator-<pod_id>`. `collector_id` should be unique per
 collector instance, such as the pod name. The `POD_NAME` environment variable is convenient since this is supplied
 to collector instance pods by default.
 
 
 ### RBAC
-The ServiceAccount that the TargetAllocator runs as, has to have access to the CRs and the namespaces to watch for the pod and service monitors. A role like this will provide that
-access.
+
+Before the TargetAllocator can start scraping, you need to set up a Kubernetes RBAC (role-based access controls). This means that you need to have a `ServiceAccount` and corresponding cluster roles so that the TargetAllocator has access to all of the necessary resources to pull metrics from.
+
+You can create your own `ServiceAccount`, and reference it in `spec.targetAllocator.serviceAccount` in your `OpenTelemetryCollector` CR. You’ll then need to configure the `ClusterRole` and `ClusterRoleBinding` for this `ServiceAccount`, as per below.
+
+```yaml
+  targetAllocator:
+    enabled: true
+    serviceAccount: opentelemetry-targetallocator-sa
+    prometheusCR:
+      enabled: true
+```
+
+> 🚨 **Note**: The Collector part of this same CR *also* has a serviceAccount key which only affects the collector and *not*
+the TargetAllocator.
+
+If you omit the `ServiceAccount` name, the TargetAllocator creates a `ServiceAccount` for you. The `ServiceAccount`’s default name is a concatenation of the Collector name and the `-collector` suffix. By default, this `ServiceAccount` has no defined policy, so you’ll need to create your own `ClusterRole` and `ClusterRoleBinding` for it, as per below.
+
+The role below will provide the minimum access required for the Target Allocator to query all the targets it needs based on any Prometheus configurations:
+
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
@@ -144,8 +162,9 @@ rules:
   - namespaces
   verbs: ["get", "list", "watch"]
 ```
-In addition, the TargetAllocator needs the same permissions as a Prometheus instance would to find the matching targets
-from the CR instances.
+
+If you enable the the `prometheusCR` (set `spec.targetAllocator.prometheusCR.enabled` to `true`) in the `OpenTelemetryCollector` CR, you will also need to define the following roles. These give the TargetAllocator access to the `PodMonitor` and `ServiceMonitor` CRs. It also gives namespace access to the `PodMonitor` and `ServiceMonitor`.
+
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
@@ -177,19 +196,9 @@ rules:
 - nonResourceURLs: ["/metrics"]
   verbs: ["get"]
 ```
-These roles can be combined.
 
-A ServiceAccount bound with the above permissions in the namespaces that are to be monitored can then be referenced in
-the `targetAllocator:` part of the OpenTelemetryCollector CR.
-```yaml
-  targetAllocator:
-    enabled: true
-    serviceAccount: opentelemetry-targetallocator-sa
-    prometheusCR:
-      enabled: true
-```
-**Note**: The Collector part of this same CR *also* has a serviceAccount key which only affects the collector and *not*
-the TargetAllocator.
+> ✨ The above roles can be combined into a single role.
+
 
 ### Service / Pod monitor endpoint credentials