diff --git a/cmd/otel-allocator/README.md b/cmd/otel-allocator/README.md index 7b4741d42b..225efc0a42 100644 --- a/cmd/otel-allocator/README.md +++ b/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 diff --git a/docs/crd-changelog.md b/docs/crd-changelog.md index 3719211495..dfb9019ba6 100644 --- a/docs/crd-changelog.md +++ b/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