From 6844430d2eb195016f0061c5152fc7ca38815bed Mon Sep 17 00:00:00 2001
From: Andreas Gerstmayr <agerstmayr@redhat.com>
Date: Mon, 7 Jul 2025 17:46:00 +0200
Subject: [PATCH] OBSDOCS-1585: Document how to run the OTel Collector as
 sidecar, deployment, daemonset and statefulset

Signed-off-by: Andreas Gerstmayr <agerstmayr@redhat.com>
---
 modules/otel-collector-deployment-modes.adoc  | 45 +++++++++++++++++++
 .../otel-collector-configuration-intro.adoc   |  2 +
 snippets/otel-collector-custom-resource.adoc  | 15 ++++---
 3 files changed, 55 insertions(+), 7 deletions(-)
 create mode 100644 modules/otel-collector-deployment-modes.adoc

diff --git a/modules/otel-collector-deployment-modes.adoc b/modules/otel-collector-deployment-modes.adoc
new file mode 100644
index 0000000000..47327bb740
--- /dev/null
+++ b/modules/otel-collector-deployment-modes.adoc
@@ -0,0 +1,45 @@
+//Module included in the following assemblies:
+//
+// * observability/otel/otel-collector/otel-collector-configuration-intro.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="otel-collector-deployment-modes_{context}"]
+= Deployment modes
+
+The `OpenTelemetryCollector` custom resource allows you to specify one of the following deployment modes for the OpenTelemetry Collector:
+
+Deployment:: The default.
+
+StatefulSet:: If you need to run stateful workloads, for example when using the Collector's File Storage Extension or Tail Sampling Processor, use the StatefulSet deployment mode.
+
+DaemonSet:: If you need to scrape telemetry data from every node, for example by using the Collector's Filelog Receiver to read container logs, use the DaemonSet deployment mode.
+
+Sidecar:: If you need access to log files inside a container, inject the Collector as a sidecar, and use the Collector's Filelog Receiver and a shared volume such as `emptyDir`.
++
+If you need to configure an application to send telemetry data via `localhost`, inject the Collector as a sidecar, and set up the Collector to forward the telemetry data to an external service via an encrypted and authenticated connection. The Collector runs in the same pod as the application when injected as a sidecar.
++
+[NOTE]
+====
+
+If you choose the sidecar deployment mode, then in addition to setting the `spec.mode: sidecar` field in the `OpenTelemetryCollector` custom resource CR, you must also set the `sidecar.opentelemetry.io/inject` annotation as a pod annotation or namespace annotation. If you set this annotation on both the pod and namespace, the pod annotation takes precedence if it is set to either `false` or the `OpenTelemetryCollector` CR name.
+
+As a pod annotation, the `sidecar.opentelemetry.io/inject` annotation supports several values:
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  ...
+  annotations:
+    sidecar.opentelemetry.io/inject: "<supported_value>" <1>
+...
+----
+<1> Supported values:
++
+`false`:: Does not inject the Collector. This is the default if the annotation is missing.
+`true`:: Injects the Collector with the configuration of the `OpenTelemetryCollector` CR in the same namespace.
+`<collector_name>`:: Injects the Collector with the configuration of the `<collector_name>` `OpenTelemetryCollector` CR in the same namespace.
+`<namespace>/<collector_name>`:: Injects the Collector with the configuration of the `<collector_name>` `OpenTelemetryCollector` CR in the `<namespace>` namespace.
+
+====
diff --git a/observability/otel/otel-collector/otel-collector-configuration-intro.adoc b/observability/otel/otel-collector/otel-collector-configuration-intro.adoc
index ee280a5ff4..718fd01118 100644
--- a/observability/otel/otel-collector/otel-collector-configuration-intro.adoc
+++ b/observability/otel/otel-collector/otel-collector-configuration-intro.adoc
@@ -8,6 +8,8 @@ toc::[]
 
 The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {OTELShortName} resources. You can install the default configuration or modify the file.
 
+include::modules/otel-collector-deployment-modes.adoc[leveloffset=+1]
+
 include::modules/otel-collector-config-options.adoc[leveloffset=+1]
 
 include::modules/otel-creating-required-RBAC-resources-automatically.adoc[leveloffset=+1]
diff --git a/snippets/otel-collector-custom-resource.adoc b/snippets/otel-collector-custom-resource.adoc
index 1e165290e6..5b2be23007 100644
--- a/snippets/otel-collector-custom-resource.adoc
+++ b/snippets/otel-collector-custom-resource.adoc
@@ -14,9 +14,9 @@ metadata:
   name: otel
   namespace: <permitted_project_of_opentelemetry_collector_instance> # <1>
 spec:
-  mode: deployment
+  mode: <deployment_mode> # <2>
   config:
-    receivers: # <2>
+    receivers: # <3>
       otlp:
         protocols:
           grpc:
@@ -28,13 +28,13 @@ spec:
           thrift_compact: {}
           thrift_http: {}
       zipkin: {}
-    processors: # <3>
+    processors: # <4>
       batch: {}
       memory_limiter:
         check_interval: 1s
         limit_percentage: 50
         spike_limit_percentage: 30
-    exporters: # <4>
+    exporters: # <5>
       debug: {}
     service:
       pipelines:
@@ -44,6 +44,7 @@ spec:
           exporters: [debug]
 ----
 <1> The project that you have chosen for the `OpenTelemetryCollector` deployment. Project names beginning with the `openshift-` prefix are not permitted.
-<2> For details, see the "Receivers" page.
-<3> For details, see the "Processors" page.
-<4> For details, see the "Exporters" page.
+<2> The deployment mode with the following supported values: the default `deployment`, `daemonset`, `statefulset`, or `sidecar`. For details, see _Deployment Modes_.
+<3> For details, see _Receivers_.
+<4> For details, see _Processors_.
+<5> For details, see _Exporters_.