From 878666f7d094eb50b0a831787eebca247641a10a Mon Sep 17 00:00:00 2001
From: Pavol Loffay <p.loffay@gmail.com>
Date: Fri, 11 Oct 2024 17:04:26 +0200
Subject: [PATCH] TRACING-4635 | document OTEL instrumentation exporter TLS

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>
---
 modules/otel-config-instrumentation.adoc | 103 +++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/modules/otel-config-instrumentation.adoc b/modules/otel-config-instrumentation.adoc
index 2a1af94e03..6485ddf6a5 100644
--- a/modules/otel-config-instrumentation.adoc
+++ b/modules/otel-config-instrumentation.adoc
@@ -98,6 +98,32 @@ spec:
 
 |===
 
+.Default protocol for auto-instrumentation
+[options="header"]
+[cols="a, a"]
+|===
+|Auto-instrumentation | Default protocol
+
+|Java 1.x
+|`otlp/grpc`
+
+|Java 2.x
+|`otlp/http`
+
+|Python
+|`otlp/http`
+
+|+.NET+
+|`otlp/http`
+
+|Go
+|`otlp/http`
+
+|Apache HTTP Server
+|`otlp/grpc`
+
+|===
+
 [id="otel-configuration-of-opentelemetry-sdk-variables_{context}"]
 == Configuration of the OpenTelemetry SDK variables
 
@@ -132,6 +158,83 @@ You can use the `instrumentation.opentelemetry.io/inject-sdk` annotation in the
 
 |===
 
+[id="otel-instrumentation-options_exporter_{context}"]
+== Exporter configuration
+
+Although the `Instrumentation` custom resource supports setting up one or more exporters per signal, auto-instrumentation configures only the OTLP Exporter. So you must configure the endpoint to point to the OTLP Receiver on the Collector.
+
+.Sample exporter TLS CA configuration using a config map
+[source,yaml]
+----
+apiVersion: opentelemetry.io/v1alpha1
+kind: Instrumentation
+# ...
+spec
+# ...
+  exporter:
+    endpoint: https://production-collector.observability.svc.cluster.local:4317  # <1>
+    tls:
+      configMapName: ca-bundle  # <2>
+      ca_file: service-ca.crt # <3>
+# ...
+----
+<1> Specifies the OTLP endpoint using the HTTPS scheme and TLS.
+<2> Specifies the name of the config map. The config map must already exist in the namespace of the pod injecting the auto-instrumentation.
+<3> Points to the CA certificate in the config map or the absolute path to the certificate if the certificate is already present in the workload file system.
+
+.Sample exporter mTLS configuration using a Secret
+[source,yaml]
+----
+apiVersion: opentelemetry.io/v1alpha1
+kind: Instrumentation
+# ...
+spec
+# ...
+  exporter:
+    endpoint: https://production-collector.observability.svc.cluster.local:4317  # <1>
+    tls:
+      secretName: serving-certs # <2>
+      ca_file: service-ca.crt # <3>
+      cert_file: tls.crt # <4>
+      key_file: tls.key # <5>
+# ...
+----
+<1> Specifies the OTLP endpoint using the HTTPS scheme and TLS.
+<2> Specifies the name of the Secret for the `ca_file`, `cert_file`, and `key_file` values. The Secret must already exist in the namespace of the pod injecting the auto-instrumentation.
+<3> Points to the CA certificate in the Secret or the absolute path to the certificate if the certificate is already present in the workload file system.
+<4> Points to the client certificate in the Secret or the absolute path to the certificate if the certificate is already present in the workload file system.
+<5> Points to the client key in the Secret or the absolute path to a key if the key is already present in the workload file system.
+
+[NOTE]
+====
+You can provide the CA certificate in a config map or Secret. If you provide it in both, the config map takes higher precedence than the Secret.
+====
+
+.Example configuration for CA bundle injection by using a config map and `Instrumentation` CR
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: otelcol-cabundle
+  namespace: tutorial-application
+  annotations:
+    service.beta.openshift.io/inject-cabundle: "true"
+# ...
+---
+apiVersion: opentelemetry.io/v1alpha1
+kind: Instrumentation
+metadata:
+  name: my-instrumentation
+spec:
+  exporter:
+    endpoint: https://simplest-collector.tracing-system.svc.cluster.local:4317
+    tls:
+      configMapName: otelcol-cabundle
+      ca: service-ca.crt
+# ...
+----
+
 [id="otel-configuration-of-apache-http-server-auto-instrumentation_{context}"]
 == Configuration of the Apache HTTP Server auto-instrumentation