Add documentation about the TA CRD

Author: swiatekm

cmd/otel-allocator/README.md

@@ -86,6 +86,7 @@ The easiest way to do this is to grab a copy of the individual [`PodMonitor`](ht
 > ✨ For more information on configuring the `PodMonitor` and `ServiceMonitor`, check out the [PodMonitor API](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#monitoring.coreos.com/v1.PodMonitor) and the [ServiceMonitor API](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#monitoring.coreos.com/v1.ServiceMonitor).
 
 # Usage
+
 The `spec.targetAllocator:` controls the TargetAllocator general properties. Full API spec can be found here: [api.md#opentelemetrycollectorspectargetallocator](../../docs/api.md#opentelemetrycollectorspectargetallocator)
 
 A basic example that deploys.
@@ -122,6 +123,51 @@ In essence, Prometheus Receiver configs are overridden with a `http_sd_config` d
 Allocator, these are then loadbalanced/sharded to the Collectors. The [Prometheus Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/README.md) configs that are overridden
 are what will be distributed with the same name.
 
+## TargetAllocator CRD
+
+The `spec.targetAllocator` attribute allows very limited control over the target allocator resources. More customization is possible by using
+the `TargetAllocator` CRD. We create the `TargetAllocator` CR, and then add its name in the `opentelemetry.io/target-allocator` label on the respective OpenTelemetryCollector CR.
+
+The basic example from above looks as follows with this setup:
+
+```yaml
+apiVersion: opentelemetry.io/v1beta1
+kind: OpenTelemetryCollector
+metadata:
+  name: collector-with-ta
+  labels:
+    opentelemetry.io/target-allocator: ta
+spec:
+  mode: statefulset
+  config:
+    receivers:
+      prometheus:
+        config:
+          scrape_configs:
+          - job_name: 'otel-collector'
+            scrape_interval: 10s
+            static_configs:
+            - targets: [ '0.0.0.0:8888' ]
+
+    exporters:
+      debug: {}
+
+    service:
+      pipelines:
+        metrics:
+          receivers: [prometheus]
+          exporters: [debug]
+---
+apiVersion: opentelemetry.io/v1alpha1
+kind: TargetAllocator
+metadata:
+  name: ta
+spec:
+```
+
+Note that the scrape configs can be specified either in the prometheus receiver configuration, or directly in the TargetAllocator CRD. The resultant
+target allocator will use both.
+
 ## PrometheusCR specifics
 
 TargetAllocator discovery of PrometheusCRs can be turned on by setting

docs/crd-changelog.md

@@ -3,6 +3,86 @@
 This document explains major changes made in new CRD versions. It is intended to help users migrate and take
 advantage of the new features.
 
+## TargetAllocator.opentelemetry.io/v1alpha1
+
+The target allocator is an application that can allocate Prometheus scrape targets to OpenTelemetry Collectors using the prometheus receiver,
+allowing transparent horizontal scaling for Prometheus metrics collection. You can learn more in the target allocator's [README](../cmd/otel-allocator/README.md).
+
+Until now, it could be enabled via the `targetAllocator` sub-resource in the OpenTelemetryCollector CR. This was, and continues to be fine for
+simpler use cases. Some users needed to customize the target allocator further, and embedding all the required attributes in the
+OpenTelemetryCollector CR would've made it unnecessarily large. Instead, we introduced a separate CRD for the target allocator.
+
+The following OpenTelemetryCollector CR:
+
+```yaml
+apiVersion: opentelemetry.io/v1beta1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+spec:
+  targetAllocator:
+     enabled: true
+     prometheusCR:
+        enabled: true
+  config:
+    receivers:
+      prometheus:
+         config:
+            scrape_configs: []
+    processors:
+      batch:
+        send_batch_size: 1000
+        timeout: 10s
+    exporters:
+      debug: {}
+    service:
+      pipelines:
+        traces:
+          receivers: [prometheus]
+          processors: [batch]
+          exporters: [debug]
+```
+
+is now equivalent to the pair:
+
+```yaml
+apiVersion: opentelemetry.io/v1beta1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+  labels:
+     opentelemetry.io/target-allocator: simplest-ta
+spec:
+  config:
+    receivers:
+      prometheus:
+         config:
+            scrape_configs: []
+    processors:
+      batch:
+        send_batch_size: 1000
+        timeout: 10s
+    exporters:
+      debug: {}
+    service:
+      pipelines:
+        traces:
+          receivers: [prometheus]
+          processors: [batch]
+          exporters: [debug]
+---
+apiVersion: opentelemetry.io/v1alpha1
+kind: TargetAllocator
+metadata:
+   name: simplest-ta
+spec:
+   prometheusCR:
+      enabled: true
+```
+
+> [!NOTE]  
+> The OpenTelemetryCollector is connected to the TargetAllocator by setting the `opentelemetry.io/target-allocator` label on the former.
+
 ## OpenTelemetryCollector.opentelemetry.io/v1beta1 
 
 ### Migration