WIP

Author: aurbiztondo-splunk

_includes/gdi/collector-common-options.rst

@@ -2,4 +2,5 @@ The Splunk Distribution of the OpenTelemetry Collector has the following configu
 
 * :ref:`collector-common-config-auth`
 * :ref:`collector-common-config-grcp`
-* :ref:`collector-common-config-net`
+* :ref:`collector-common-config-net`
+* :ref:`collector-common-config-tls`

gdi/opentelemetry/collector-common-config.rst

@@ -12,9 +12,10 @@ Common configuration options
     :titlesonly:
     :hidden:
 
-    Authentication <common-config/collector-common-config-auth.rst>
+    Authentication settings <common-config/collector-common-config-auth.rst>
     gRCP settings <common-config/collector-common-config-grcp.rst>
     Network settings <common-config/collector-common-config-net.rst>
+    TLS settings <common-config/collector-common-config-net.rst>
 
 .. note:: The following list might not contain all the latest additions and updates. For a complete list of Collector common settings see the ``opentelemetry`` repository in GitHub.  
 

gdi/opentelemetry/common-config/collector-common-config-auth.rst

@@ -4,21 +4,21 @@
 Configure authentication 
 *********************************************************************************
 
-You can configure two types of authentication within the Collector:
+You can configure two types of authentication for the Collector:
 
 * Server type authentication takes place in incoming HTTP/gRPC requests and is typically used by :ref:`receivers <otel-components-receivers>`. Server type authenticators include:
 
-  * :ref:`Basic Auth Extension <basic-auth-extension>`
-  * Bearer Token Extension
-  * OIDC Extension
+  * :ref:`Basic Auth extension <basic-auth-extension>`
+  * Bearer Token extension
+  * OIDC extension
 
 * Client type authentication takes place in outgoing HTTP/gRPC requests and is typically used by :ref:`exporters <otel-components-exporters>`. Client type authenticators include:  
 
-  * ASAP Client Authentication Extension
+  * ASAP Client Authentication extension
   * :ref:`Basic Auth Extension <basic-auth-extension>`
-  * Bearer Token Extension
+  * Bearer Token extension
   * :ref:`oauth2client-extension`
-  * Sigv4 Extension
+  * Sigv4 extension
 
 .. note:: You can add new authenticators by creating a new extension with the appropriate interface, ``configauth.ServerAuthenticator`` or ``configauth.ClientAuthenticator``.
 

gdi/opentelemetry/common-config/collector-common-config-grcp.rst

@@ -1,17 +1,17 @@
 .. _collector-common-config-grcp:
 
 *********************************************************************************
-Configure gRCP settings
+Configure gRCP 
 *********************************************************************************
 
 gRPC exposes a variety of settings you can adjust within individual receivers or exporters of the Collector. For more information, refer to :ref:`Golang's gRCP documentation <https://pkg.go.dev/google.golang.org/grpc>`.
 
+.. note:: To configure TLS, see :ref:`collector-collector-common-config-tls`.
+
 Client configuration
 =============================================================================================
 
-Exporters leverage client configuration.
-
-Note that client configuration supports TLS configuration, the configuration parameters are also defined under tls like server configuration. For more information, see configtls README.
+:ref:`Exporters <otel-components-exporters>` leverage client configuration.
 
 balancer_name: Default before v0.103.0 is pick_first, default for v0.103.0 is round_robin. See issue. To restore the previous behavior, set balancer_name to pick_first.
 compression: Compression type to use among gzip, snappy, zstd, and none.
@@ -29,18 +29,20 @@ Please note that per_rpc_auth which allows the credentials to send for every RPC
 
 Example:
 
-exporters:
-  otlp:
-    endpoint: otelcol2:55690
-    auth:
-      authenticator: some-authenticator-extension
-    tls:
-      ca_file: ca.pem
-      cert_file: cert.pem
-      key_file: key.pem
-    headers:
-      test1: "value1"
-      "test 2": "value 2"
+.. code-block:: yaml
+
+   exporters:
+      otlp:
+         endpoint: otelcol2:55690
+         auth:
+            authenticator: some-authenticator-extension
+         tls:
+            ca_file: ca.pem
+            cert_file: cert.pem
+            key_file: key.pem
+         headers:
+            test1: "value1"
+            "test 2": "value 2"
 
 Compression Comparison
 configgrpc_benchmark_test.go contains benchmarks comparing the supported compression algorithms. It performs compression using gzip, zstd, and snappy compression on small, medium, and large sized log, trace, and metric payloads. Each test case outputs the uncompressed payload size, the compressed payload size, and the average nanoseconds spent on compression.

gdi/opentelemetry/common-config/collector-common-config-net.rst

@@ -31,7 +31,6 @@ You can configure the following network settings:
 
 * ``dialer_timeout``. No timeout by default. The maximum amount of time a dial waits for a connect to complete. 
 
-
 .. note:: TCP receivers only require the ``endpoint`` configuration setting.
 
 

gdi/opentelemetry/common-config/collector-common-config-tls.rst

@@ -0,0 +1,117 @@
+.. _collector-common-config-tls:
+
+*********************************************************************************
+Configure TLS
+*********************************************************************************
+
+:ref:`Collector receivers <otel-components-receivers>` leverage network configuration to set connection and transport information.
+
+Crypto TLS exposes a variety of settings. Several of these settings are available for configuration within individual receivers or exporters.
+
+Note that mutual TLS (mTLS) is also supported.
+
+TLS / mTLS Configuration
+By default, TLS is enabled:
+
+insecure (default = false): whether to enable client transport security for the exporter's HTTPs or gRPC connection. See grpc.WithInsecure() for gRPC.
+As a result, the following parameters are also required:
+
+cert_file: Path to the TLS cert to use for TLS required connections. Should only be used if insecure is set to false.
+
+cert_pem: Alternative to cert_file. Provide the certificate contents as a string instead of a filepath.
+key_file: Path to the TLS key to use for TLS required connections. Should only be used if insecure is set to false.
+
+key_pem: Alternative to key_file. Provide the key contents as a string instead of a filepath.
+A certificate authority may also need to be defined:
+
+ca_file: Path to the CA cert. For a client this verifies the server certificate. For a server this verifies client certificates. If empty uses system root CA. Should only be used if insecure is set to false.
+ca_pem: Alternative to ca_file. Provide the CA cert contents as a string instead of a filepath.
+You can also combine defining a certificate authority with the system certificate authorities.
+
+include_system_ca_certs_pool (default = false): whether to load the system certificate authorities pool alongside the certificate authority.
+Additionally you can configure TLS to be enabled but skip verifying the server's certificate chain. This cannot be combined with insecure since insecure won't use TLS at all.
+
+insecure_skip_verify (default = false): whether to skip verifying the certificate or not.
+Minimum and maximum TLS version can be set:
+
+IMPORTANT: TLS 1.0 and 1.1 are deprecated due to known vulnerabilities and should be avoided.
+
+min_version (default = "1.2"): Minimum acceptable TLS version.
+
+options: ["1.0", "1.1", "1.2", "1.3"]
+max_version (default = "" handled by crypto/tls - currently TLS 1.3): Maximum acceptable TLS version.
+
+options: ["1.0", "1.1", "1.2", "1.3"]
+Explicit cipher suites can be set. If left blank, a safe default list is used. See https://go.dev/src/crypto/tls/cipher_suites.go for a list of supported cipher suites.
+
+cipher_suites: (default = []): List of cipher suites to use.
+Example:
+
+  cipher_suites:
+    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
+    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
+    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
+Additionally certificates may be reloaded by setting the below configuration.
+
+reload_interval (optional) : ReloadInterval specifies the duration after which the certificate will be reloaded. If not set, it will never be reloaded. Accepts a duration string, valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+How TLS/mTLS is configured depends on whether configuring the client or server. See below for examples.
+
+Client Configuration
+Exporters leverage client configuration. The TLS configuration parameters are defined under tls, like server configuration.
+
+Beyond TLS configuration, the following setting can optionally be configured:
+
+server_name_override: If set to a non-empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests (typically used for testing).
+Example:
+
+exporters:
+  otlp:
+    endpoint: myserver.local:55690
+    tls:
+      insecure: false
+      ca_file: server.crt
+      cert_file: client.crt
+      key_file: client.key
+      min_version: "1.1"
+      max_version: "1.2"
+  otlp/insecure:
+    endpoint: myserver.local:55690
+    tls:
+      insecure: true
+  otlp/secure_no_verify:
+    endpoint: myserver.local:55690
+    tls:
+      insecure: false
+      insecure_skip_verify: true
+Server Configuration
+Receivers leverage server configuration.
+
+Beyond TLS configuration, the following setting can optionally be configured (required for mTLS):
+
+client_ca_file: Path to the TLS cert to use by the server to verify a client certificate. (optional) This sets the ClientCAs and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Please refer to https://godoc.org/crypto/tls#Config for more information.
+client_ca_file_reload (default = false): Reload the ClientCAs file when it is modified.
+Example:
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: mysite.local:55690
+        tls:
+          cert_file: server.crt
+          key_file: server.key
+  otlp/mtls:
+    protocols:
+      grpc:
+        endpoint: mysite.local:55690
+        tls:
+          client_ca_file: client.pem
+          cert_file: server.crt
+          key_file: server.key
+  otlp/notls:
+    protocols:
+      grpc:
+        endpoint: mysite.local:55690
+
+
+