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

@@ -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.
+
+====

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]

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_.