TRACING-3802| Add target allocator to opentelemetry

modules/otel-config-target-allocator.adoc

@@ -0,0 +1,93 @@
+// Module included in the following assemblies:
+//
+// * otel/otel-configuring.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="otel-collector-ta-{context}"]
+= Target allocator
+
+The target allocator is an optional component of the OpenTelemetry Operator that shards scrape targets across the deployed fleet of OpenTelemetry Collector instances. The target allocator integrates with the Prometheus `PodMonitor` and `ServiceMonitor` custom resources. When the target allocator is enabled,  the OpenTelemetry Operator adds `http_sd_config` to the enabled `prometheus` receiver that connects to the target allocator service.
+
+.Example OpenTelemetryCollector CR with the enabled target allocator
+[source,yaml]
+----
+apiVersion: opentelemetry.io/v1alpha1
+kind: OpenTelemetryCollector
+metadata:
+  name: otel
+  namespace: observability
+spec:
+  mode: statefulset # <1>
+  targetAllocator:
+    enabled: true # <2>
+    serviceAccount: # <3>
+    prometheusCR:
+      enabled: true # <4>
+      scrapeInterval: 10s
+      serviceMonitorSelector: # <5>
+        name: app1
+      podMonitorSelector: # <6>
+        name: app2
+  config: |
+    receivers:
+      prometheus: # <7>
+        config:
+          scrape_configs: []
+    processors:
+    exporters:
+      debug:
+    service:
+      pipelines:
+        metrics:
+          receivers: [prometheus]
+          processors: []
+          exporters: [debug]
+----
+<1> When the target allocator is enabled, the deployment mode must be set to `statefulset`.
+<2> Enables the target allocator. Defaults to `false`.
+<3> The service account name of the target allocator deployment. The service account needs to have RBAC to get the `ServiceMonitor`, `PodMonitor` custom resources, and other objects from the cluster to properly set labels on scraped metrics. The default service name is `<collector_name>-targetallocator`.
+<4> Enables integration with the Prometheus `PodMonitor` and `ServiceMonitor` custom resources.
+<5> Label selector for the Prometheus `ServiceMonitor` custom resources. When left empty, enables all service monitors.
+<6> Label selector for the Prometheus `PodMonitor` custom resources. When left empty, enables all pod monitors.
+<7> Prometheus receiver with the minimal, empty `scrape_config: []` configuration option.
+
+The target allocator deployment uses the Kubernetes API to get relevant objects from the cluster, so it requires a custom RBAC configuration.
+
+.RBAC configuration for the target allocator service account
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: otel-targetallocator
+rules:
+  - apiGroups: [""]
+    resources:
+      - services
+      - pods
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["monitoring.coreos.com"]
+    resources:
+      - servicemonitors
+      - podmonitors
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["discovery.k8s.io"]
+    resources:
+      - endpointslices
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: otel-targetallocator
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: otel-targetallocator
+subjects:
+  - kind: ServiceAccount
+    name: otel-targetallocator # <1>
+    namespace: observability # <2>
+----
+<1> The name of the target allocator service account mane.
+<2> The namespace of the target allocator service account.

otel/otel-configuring.adoc

@@ -12,6 +12,8 @@ include::modules/otel-config-collector.adoc[leveloffset=+1]
 include::modules/otel-config-multicluster.adoc[leveloffset=+1]
 include::modules/otel-config-send-metrics-monitoring-stack.adoc[leveloffset=+1]
 
+include::modules/otel-config-target-allocator.adoc[leveloffset=+1]
+
 [id="setting-up-monitoring-for-otel"]
 == Setting up monitoring for the {OTELShortName}