docs: Documentation for Traces mTLS support

apis/telemetry/v1alpha1/shared_types.go

@@ -51,13 +51,13 @@ type Header struct {
 type OtlpTLS struct {
 	// Defines whether to send requests using plaintext instead of TLS.
 	Insecure bool `json:"insecure"`
-	// Defines whether to skip TLS certificate verification.
+	// Defines whether to skip server certificate verification when using TLS.
 	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
-	// Defines the CA certificate.
+	// Defines an optional CA certificate for server certificate verification when using TLS. The certificate needs to be provided in PEM format.
 	CA ValueType `json:"ca,omitempty"`
-	// Defines the client certificate.
+	// Defines a client certificate to use when using TLS. The certificate needs to be provided in PEM format.
 	Cert ValueType `json:"cert,omitempty"`
-	// Defines the client key.
+	// Defines the client key to use when using TLS. The key needs to be provided in PEM format.
 	Key ValueType `json:"key,omitempty"`
 }
 

config/crd/bases/telemetry.kyma-project.io_tracepipelines.yaml

@@ -182,7 +182,9 @@ spec:
                         description: Defines TLS options for the OTLP output.
                         properties:
                           ca:
-                            description: Defines the CA certificate.
+                            description: Defines an optional CA certificate for server
+                              certificate verification when using TLS. The certificate
+                              needs to be provided in PEM format.
                             properties:
                               value:
                                 description: Value that can contain references to
@@ -205,7 +207,9 @@ spec:
                                 type: object
                             type: object
                           cert:
-                            description: Defines the client certificate.
+                            description: Defines a client certificate to use when
+                              using TLS. The certificate needs to be provided in PEM
+                              format.
                             properties:
                               value:
                                 description: Value that can contain references to
@@ -232,10 +236,12 @@ spec:
                               instead of TLS.
                             type: boolean
                           insecureSkipVerify:
-                            description: Defines whether to skip TLS certificate verification.
+                            description: Defines whether to skip server certificate
+                              verification when using TLS.
                             type: boolean
                           key:
-                            description: Defines the client key.
+                            description: Defines the client key to use when using
+                              TLS. The key needs to be provided in PEM format.
                             properties:
                               value:
                                 description: Value that can contain references to

config/development/telemetry.kyma-project.io_metricpipelines.yaml

@@ -217,7 +217,9 @@ spec:
                         description: Defines TLS options for the OTLP output.
                         properties:
                           ca:
-                            description: Defines the CA certificate.
+                            description: Defines an optional CA certificate for server
+                              certificate verification when using TLS. The certificate
+                              needs to be provided in PEM format.
                             properties:
                               value:
                                 description: Value that can contain references to
@@ -240,7 +242,9 @@ spec:
                                 type: object
                             type: object
                           cert:
-                            description: Defines the client certificate.
+                            description: Defines a client certificate to use when
+                              using TLS. The certificate needs to be provided in PEM
+                              format.
                             properties:
                               value:
                                 description: Value that can contain references to
@@ -267,10 +271,12 @@ spec:
                               instead of TLS.
                             type: boolean
                           insecureSkipVerify:
-                            description: Defines whether to skip TLS certificate verification.
+                            description: Defines whether to skip server certificate
+                              verification when using TLS.
                             type: boolean
                           key:
-                            description: Defines the client key.
+                            description: Defines the client key to use when using
+                              TLS. The key needs to be provided in PEM format.
                             properties:
                               value:
                                 description: Value that can contain references to

docs/user/02-logs.md

@@ -14,7 +14,7 @@ Your application must log to `stdout` or `stderr`, which is the recommended way
 
 The Telemetry module provides [Fluent Bit](https://fluentbit.io/) as a log agent. Fluent Bit collects all application logs of the cluster workload and ships them to a backend.
 
-![Architecture](./assets/logging-arch.drawio.svg)
+![Architecture](./assets/logs-arch.drawio.svg)
 
 1. Container logs are stored by the Kubernetes container runtime under the `var/log` directory and its subdirectories.
 2. Fluent Bit runs as a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) (one instance per Node), detects any new log files in the folder, and tails them using a filesystem buffer for reliability.
@@ -28,7 +28,7 @@ The Telemetry module provides [Fluent Bit](https://fluentbit.io/) as a log agent
 Fluent Bit comes with a pipeline concept, which supports a flexible combination of inputs with outputs and filtering in between; for details, see [Fluent Bit: Output](https://docs.fluentbit.io/manual/concepts/data-pipeline/output).
 Kyma's Telemetry module brings a predefined setup of the Fluent Bit DaemonSet and a base configuration, which assures that the application logs of the workloads in the cluster are processed reliably and efficiently. Additionally, the telemetry module provides a Kubernetes API called `LogPipeline` to configure outputs with some filtering capabilities.
 
-![Pipeline Concept](./assets/logging-pipelines.drawio.svg)
+![Pipeline Concept](./assets/logs-pipelines.drawio.svg)
 
 1. A central `tail` input plugin reads the application logs.
 
@@ -42,7 +42,7 @@ This approach assures a reliable buffer management and isolation of pipelines, w
 
 The LogPipeline resource is managed by Telemetry Manager, a typical Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) responsible for managing the custom parts of the Fluent Bit configuration.
 
-![Manager resources](./assets/logging-resources.drawio.svg)
+![Manager resources](./assets/logs-resources.drawio.svg)
 
 Telemetry Manager watches all LogPipeline resources and related Secrets. Whenever the configuration changes, Telemetry Manager validates the configuration (with a [validating webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)) and generates a new configuration for the Fluent Bit DaemonSet, where several ConfigMaps for the different aspects of the configuration are generated. Furthermore, referenced Secrets are copied into one Secret that is also mounted to the DaemonSet.
 
@@ -324,7 +324,7 @@ spec:
 
 After a log record has been read, it is preprocessed by centrally configured plugins, like the `kubernetes` filter. Thus, when a record is ready to be processed by the sections defined in the LogPipeline definition, it has several attributes available for processing and shipment.
 
-![Flow](./assets/logging-flow.drawio.svg)
+![Flow](./assets/logs-flow.drawio.svg)
 
 Learn more about the flow of the log record through the general pipeline and the available log attributes in the following sections.
 

docs/user/03-traces.md

@@ -6,8 +6,9 @@ Observability tools aim to show the big picture, no matter if you're monitoring
 
 The diagram shows how distributed tracing helps to track the request path:
 
-![Distributed tracing](./assets/tracing-intro.drawio.svg)
+![Distributed tracing](./assets/traces-intro.drawio.svg)
 
+The goal of the Telemetry Module is to support you in collecting all relevant trace data in a Kyma cluster and ship them to a backend for further analysis. Hereby, relevant Kyma modules like Istio or Serverless will contribute instantly and typical enrichment of the data is happening.
 ## Prerequisites
 
 For a complete recording of a distributed trace, it is [essential](https://www.w3.org/TR/trace-context/#problem-statement) that every involved component is at least propagating the trace context. In Kyma, all components involved in users' requests support the [W3C Trace Context protocol](https://www.w3.org/TR/trace-context), which is a vendor-neutral protocol gaining more and more support by all kinds of vendors and tools. The involved Kyma components are mainly Istio, Serverless, and Eventing.
@@ -20,7 +21,7 @@ Furthermore, an application should enrich a trace with additional span data and
 
 The Telemetry module provides an in-cluster central deployment of an [OTel Collector](https://opentelemetry.io/docs/collector/) acting as a gateway. The gateway exposes endpoints for the OTLP protocol for GRPC and HTTP-based communication using the dedicated `telemetry-otlp-traces` service, where all Kyma components and users' applications should send the trace data to.
 
-![Architecture](./assets/tracing-arch.drawio.svg)
+![Architecture](./assets/traces-arch.drawio.svg)
 
 1. An end-to-end request is triggered and populates across the distributed application. Every involved component propagates the trace context using the [W3C Trace Context](https://www.w3.org/TR/trace-context/) protocol.
 2. The involved components that have contributed a new span to the trace send the related span data to the trace gateway using the `telemetry-otlp-traces` service. The communication happens based on the [OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md) protocol either using GRPC or HTTP.
@@ -30,8 +31,8 @@ The Telemetry module provides an in-cluster central deployment of an [OTel Colle
 1. The backend can also run out-cluster, if authentication has been set up.
 1. The trace data can be consumed using the backend system.
 
-### OTel Collector
-The OTel Collector comes with a [concept](https://opentelemetry.io/docs/collector/configuration/) of pipelines consisting of receivers, processors, and exporters, with which you can flexibly plug pipelines together. Kyma's TracePipeline provides a hardened setup of an OTel Collector and also abstracts the underlying pipeline concept. Such abstraction has the following benefits:
+### Trace Gateway
+The Trace Gateway is running as a central component in a Kyma cluster where all parties of traces can send its individual span data to. The gateway will collect, enrich and dispatch the data centrally to the configured backend. The gateway is based on the Otel Collector and comes with a [concept](https://opentelemetry.io/docs/collector/configuration/) of pipelines consisting of receivers, processors, and exporters, with which you can flexibly plug pipelines together. Kyma's TracePipeline provides a hardened setup of an OTel Collector and also abstracts the underlying pipeline concept. Such abstraction has the following benefits:
 - Supportability - all features are tested and supported
 - Migratability - smooth migration experiences when switching underlying technologies or architectures
 - Native Kubernetes support - API provided by Kyma allows for an easy integration with Secrets, for example, served by the [SAP BTP Service Operator](https://github.com/SAP/sap-btp-service-operator#readme). Telemetry Manager takes care of the full lifecycle.
@@ -42,7 +43,7 @@ The downside is that only a limited set of features is available. If you want to
 ### Telemetry Manager
 The TracePipeline resource is managed by Telemetry Manager, a typical Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) responsible for managing the custom parts of the OTel Collector configuration.
 
-![Manager resources](./assets/tracing-resources.drawio.svg)
+![Manager resources](./assets/traces-resources.drawio.svg)
 
 Telemetry Manager watches all TracePipeline resources and related Secrets. Whenever the configuration changes, it validates the configuration and generates a new configuration for OTel Collector, where a ConfigMap for the configuration is generated. Referenced Secrets are copied into one Secret that is mounted to the OTel Collector as well.
 Furthermore, the manager takes care of the full lifecycle of the OTel Collector Deployment itself. Only if there is a TracePipeline defined, the collector is deployed. At anytime, you can opt out of using the tracing feature by not specifying a TracePipeline.
@@ -121,19 +122,43 @@ spec:
 To integrate with external systems, you must configure authentication details. At the moment, Basic Authentication and custom headers are supported.
 
 <div tabs>
+  <details>
+    <summary>Mutual TLS</summary>
+
+  ```yaml
+  apiVersion: telemetry.kyma-project.io/v1alpha1
+  kind: TracePipeline
+  metadata:
+    name: backend
+  spec:
+    output:
+      otlp:
+        endpoint:
+          value: https://backend.example.com/otlp:4317
+        tls:
+          cert:
+            value: |
+              -----BEGIN CERTIFICATE-----
+              ...
+          key:
+            value: |
+              -----BEGIN RSA PRIVATE KEY-----
+              ...
+  ```
+  </details>
   <details>
     <summary>Basic authentication</summary>
 
   ```yaml
   apiVersion: telemetry.kyma-project.io/v1alpha1
   kind: TracePipeline
   metadata:
-    name: jaeger
+    name: backend
   spec:
     output:
       otlp:
         endpoint:
-          value: http://jaeger-collector.jaeger.svc.cluster.local:4317
+          value: https://backend.example.com/otlp:4317
         authentication:
           basic:
             user:
@@ -149,12 +174,12 @@ To integrate with external systems, you must configure authentication details. A
   apiVersion: telemetry.kyma-project.io/v1alpha1
   kind: TracePipeline
   metadata:
-    name: jaeger
+    name: backend
   spec:
     output:
       otlp:
         endpoint:
-          value: http://jaeger-collector.jaeger.svc.cluster.local:4317
+          value: https://backend.example.com/otlp:4317
         headers:
           - name: Authorization
             value: "Bearer myToken"
@@ -169,14 +194,42 @@ Integrations into external systems usually require authentication details dealin
 Use the **valueFrom** attribute to map Secret keys as in the following examples:
 
 <div tabs>
+  <details>
+    <summary>Mutual TLS</summary>
+
+  ```yaml
+  apiVersion: telemetry.kyma-project.io/v1alpha1
+  kind: TracePipeline
+  metadata:
+    name: backend
+  spec:
+    output:
+      otlp:
+        endpoint:
+          value: https://backend.example.com/otlp:4317
+        tls:
+          cert:
+            valueFrom:
+              secretKeyRef:
+                  name: backend
+                  namespace: default
+                  key: cert
+          key:
+            valueFrom:
+              secretKeyRef:
+                  name: backend
+                  namespace: default
+                  key: key
+  ```
+  </details>
   <details>
     <summary>Basic authentication</summary>
 
   ```yaml
   apiVersion: telemetry.kyma-project.io/v1alpha1
   kind: TracePipeline
   metadata:
-    name: jaeger
+    name: backend
   spec:
     output:
       otlp: