Improve allocation strategy documentation (#2848)

Author: swiatekm

apis/v1alpha1/opentelemetrycollector_types.go

@@ -317,6 +317,7 @@ type OpenTelemetryTargetAllocator struct {
 	// AllocationStrategy determines which strategy the target allocator should use for allocation.
 	// The current options are least-weighted, consistent-hashing and per-node. The default is
 	// consistent-hashing.
+	// WARNING: The per-node strategy currently ignores targets without a Node, like control plane components.
 	// +optional
 	// +kubebuilder:default:=consistent-hashing
 	AllocationStrategy OpenTelemetryTargetAllocatorAllocationStrategy `json:"allocationStrategy,omitempty"`

apis/v1beta1/opentelemetrycollector_types.go

@@ -143,6 +143,7 @@ type TargetAllocatorEmbedded struct {
 	// AllocationStrategy determines which strategy the target allocator should use for allocation.
 	// The current options are least-weighted, consistent-hashing and per-node. The default is
 	// consistent-hashing.
+	// WARNING: The per-node strategy currently ignores targets without a Node, like control plane components.
 	// +optional
 	// +kubebuilder:default:=consistent-hashing
 	AllocationStrategy TargetAllocatorAllocationStrategy `json:"allocationStrategy,omitempty"`

apis/v1beta1/targetallocator_types.go

@@ -61,7 +61,9 @@ type TargetAllocatorSpec struct {
 	// CollectorSelector is the selector for Collector Pods the target allocator will allocate targets to.
 	CollectorSelector metav1.LabelSelector `json:"collectorSelector,omitempty"`
 	// AllocationStrategy determines which strategy the target allocator should use for allocation.
-	// The current options are least-weighted and consistent-hashing. The default option is consistent-hashing
+	// The current options are least-weighted, consistent-hashing and per-node. The default is
+	// consistent-hashing.
+	// WARNING: The per-node strategy currently ignores targets without a Node, like control plane components.
 	// +optional
 	// +kubebuilder:default:=consistent-hashing
 	AllocationStrategy TargetAllocatorAllocationStrategy `json:"allocationStrategy,omitempty"`

cmd/otel-allocator/README.md

@@ -30,6 +30,33 @@ sequenceDiagram
   OTel Collectors ->>Metrics Targets: 5. Scrape Metrics target
 ```
 
+### Allocation strategies
+
+Several target allocation strategies are available. Some strategies may only make sense for a given Collector deployment
+mode. For example, the `per-node` strategy only works correctly with a Collector deployed as a DaemonSet.
+
+#### `consistent-hashing`
+
+A consistent hashing strategy implementing the [following algorithm][consistent_hashing]. Only the target url is hashed
+to prevent label changes from causing targets to be moved between collectors. This strategy consistently assigns
+targets to the same collectors, but will experience rebalancing when the collector count changes.
+
+This is the default.
+
+#### `least-weighted`
+
+A strategy that simply assigns the target to the collector with the least number of targets. It achieves more stability
+in target assignment when collector count changes, but at the cost of less even distribution of targets.
+
+#### `per-node`
+
+This strategy assigns each target to the collector running on the same Node the target is. As such, it only makes sense
+to use it with a collector running as a DaemonSet.
+
+> [!WARNING]  
+> The per-node strategy ignores targets not assigned to a Node, like for example control plane components.
+
+[consistent_hashing]: https://blog.research.google/2017/04/consistent-hashing-with-bounded-loads.html
 ## Discovery of Prometheus Custom Resources
 
 The Target Allocator also provides for the discovery of [Prometheus Operator CRs](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md), namely the [ServiceMonitor and PodMonitor](https://github.com/open-telemetry/opentelemetry-operator/tree/main/cmd/otel-allocator#target-allocator). The ServiceMonitors and the PodMonitors purpose is to inform the Target Allocator (or PrometheusOperator) to add a new job to their scrape configuration. The Target Allocator then provides the jobs to the OTel Collector [Prometheus Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/README.md). 

docs/api.md

@@ -21565,7 +21565,8 @@ TargetAllocator indicates a value which determines whether to spawn a target all
         <td>
           AllocationStrategy determines which strategy the target allocator should use for allocation.
 The current options are least-weighted, consistent-hashing and per-node. The default is
-consistent-hashing.<br/>
+consistent-hashing.
+WARNING: The per-node strategy currently ignores targets without a Node, like control plane components.<br/>
           <br/>
             <i>Enum</i>: least-weighted, consistent-hashing, per-node<br/>
             <i>Default</i>: consistent-hashing<br/>