Draft

aurbiztondo-splunk · aurbiztondo-splunk · commit 3db35269145f · 2024-08-27T17:50:41.000+02:00
diff --git a/gdi/opentelemetry/common-config/collector-common-config-auth.rst b/gdi/opentelemetry/common-config/collector-common-config-auth.rst
@@ -15,12 +15,12 @@ You can configure two types of authentication for the Collector:
 * 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
-  * :ref:`Basic Auth Extension <basic-auth-extension>`
+  * :ref:`Basic Auth extension <basic-auth-extension>`
   * Bearer Token extension
   * :ref:`oauth2client-extension`
   * Sigv4 extension
 
-.. note:: You can add new authenticators by creating a new extension with the appropriate interface, ``configauth.ServerAuthenticator`` or ``configauth.ClientAuthenticator``.
+.. note:: For more details see :new-page:`Auth Configuration Settings https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configauth` in OTel's GitHub repo.
 
 Example
 =============================================================================================
diff --git a/gdi/opentelemetry/common-config/collector-common-config-grcp.rst b/gdi/opentelemetry/common-config/collector-common-config-grcp.rst
@@ -6,31 +6,39 @@ Configure gRCP
 
 gRPC exposes a variety of settings you can adjust within individual receivers or exporters of the Collector. 
 
-For more details on the available settings refer to :new-page:`gRPC Configuration Settings <https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configgrpc>` in OTel's GitHub repo and :new-page:`Golang's gRCP documentation <https://pkg.go.dev/google.golang.org/grpc>`.
-
 .. note:: 
    
    To configure transport, see :ref:`collector-common-config-net`.
 
 Configure gRCP clients 
 =============================================================================================
 
-.. note:: For more details see :new-page:`gRPC Configuration Settings https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configgrpc` in OTel's GitHub repo.
-
 To configure gRCP clients in :ref:`exporters <otel-components-exporters>` use these settings:
 
 * ``auth``. See :ref:`collector-common-config-auth`
+
 * ``balancer_name`` 
+
   * Defaults: ``pick_first`` before version 0.103.0, ``round_robin`` for v0.103.0 or higher 
+
   * Learn more at gRCP's :new-page:`Load Balancing README https://github.com/grpc/grpc-go/blob/master/examples/features/load_balancing/README.md`. 
+
 * ``compression``. 
+
   * Compression type valid values are ``gzip``, ``snappy``, ``zstd``, and ``none``
+
 * ``endpoint``
+
   * For valid syntax see :new-page:`gRPC Name Resolution <https://github.com/grpc/grpc/blob/master/doc/naming.md>`.
+
 * ``headers``
+
 * ``keepalive`` 
+
 * ``read_buffer_size``
+
 * ``tls``. See :ref:`collector-common-config-tls`.
+
 * ``write_buffer_size``
 
 For example:
@@ -50,21 +58,29 @@ For example:
             test1: "value1"
             "test 2": "value 2"
 
-Server configuration
+Configure gRCP servers 
 =============================================================================================
 
-.. note:: For more details see :new-page:`gRPC Configuration Settings https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configgrpc` in OTel's GitHub repo.
-
-To configure servers in :ref:`collector receivers <otel-components-receivers>` use these settings:
+To configure gRCP servers in :ref:`collector receivers <otel-components-receivers>` use these settings:
 
 * ``auth``. See :ref:`collector-common-config-auth`
+
 * ``keepalive``
+
 * ``max_concurrent_streams``
+
 * ``max_recv_msg_size_mib``
+
 * ``read_buffer_size``
+
 * ``tls``. See :ref:`collector-common-config-tls`
-* ``write_buffer_size``
 
+* ``write_buffer_size``
 
+Learn more
+=============================================================================================
 
+For more details on the available settings refer to: 
 
+* :new-page:`gRPC Configuration Settings <https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configgrpc>` in OTel's GitHub repo
+* :new-page:`Golang's gRCP documentation <https://pkg.go.dev/google.golang.org/grpc>`
diff --git a/gdi/opentelemetry/common-config/collector-common-config-tls.rst b/gdi/opentelemetry/common-config/collector-common-config-tls.rst
@@ -4,114 +4,178 @@
 Configure TLS
 *********************************************************************************
 
-:ref:`Collector receivers <otel-components-receivers>` leverage network configuration to set connection and transport information.
+Crypto TLS exposes a variety of settings you can adjust within individual receivers or exporters of the Collector. 
 
-Crypto TLS exposes a variety of settings. Several of these settings are available for configuration within individual receivers or exporters.
+.. note:: Mutual TLS (mTLS) is also supported.
 
-Note that mutual TLS (mTLS) is also supported.
+Configure TLS / mTLS 
+=============================================================================================
 
-TLS / mTLS Configuration
-By default, TLS is enabled:
+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:
+#. See the required and optional settings available
+#. To complete the TLS/mTLS configuration, proceed to :ref:`collector-common-config-tls-client` or :ref:`collector-common-config-tls-server` 
 
-cert_file: Path to the TLS cert to use for TLS required connections. Should only be used if insecure is set to false.
+Required settings
+---------------------------------
 
-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.
+The following settings are required:
 
-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:
+* ``insecure``. ``false`` by default. Whether to enable client transport security for the exporter's HTTPs or gRPC connection. 
 
-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.
+  * For gRCP, see :new-page:`Golang's grpc.WithInsecure() <https://pkg.go.dev/google.golang.org/grpc#WithInsecure>`.
 
-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.
+* ``cert_file``. Use only if ``insecure`` is set to ``false``. Path to the TLS cert to use for TLS required connections. 
 
-insecure_skip_verify (default = false): whether to skip verifying the certificate or not.
-Minimum and maximum TLS version can be set:
+* ``cert_pem``. Alternative to ``cert_file``. Provide the certificate contents as a string instead of a filepath.
 
-IMPORTANT: TLS 1.0 and 1.1 are deprecated due to known vulnerabilities and should be avoided.
+* ``key_file``. Use only if ``insecure`` is set to ``false``. Path to the TLS key to use for TLS required connections. 
 
-min_version (default = "1.2"): Minimum acceptable TLS version.
+* ``key_pem``: Alternative to ``key_file``. Provide the key contents as a string instead of a filepath.
 
-options: ["1.0", "1.1", "1.2", "1.3"]
-max_version (default = "" handled by crypto/tls - currently TLS 1.3): Maximum acceptable TLS version.
+Additional settings
+---------------------------------
 
-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.
+Certificate authority
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-cipher_suites: (default = []): List of cipher suites to use.
-Example:
+To define a certificate authority use:
+
+* ``ca_file``.  Use only if ``insecure`` is set to ``false``. Path to the CA cert. 
+
+  * For a client this verifies the server certificate. 
+  
+  * For a server this verifies client certificates. 
+  
+  * If empty it uses the system root CA. 
+
+* ``ca_pem``. Alternative to ``ca_file``. Provide the CA cert contents as a string instead of a filepath.
+
+To combine defining a certificate authority with the system certificate authorities use:
+
+* ``include_system_ca_certs_pool``. ``false`` by default. 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``. ``false`` by default. Whether to skip verifying the certificate or not.
+
+TLS version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. caution:: Avoid using TLS 1.0 and 1.1. Both are deprecated due to known vulnerabilities.
+
+You can set minimum and maximum TLS versions:
+
+* ``min_version``. "1.2" by default. Minimum acceptable TLS version.
+
+  * Options: "1.0", "1.1", "1.2", "1.3"
+
+* ``max_version``. "" by default. Maximum acceptable TLS version. 
+
+  * Options: "1.0", "1.1", "1.2", "1.3"
+
+Cipher suites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can set explicit cipher suites using ``cipher_suites``. 
+
+* ``[]`` by default. If left blank, a safe default list is used. 
+* See the :new-page:`Cipher suites source files <https://go.dev/src/crypto/tls/cipher_suites.go>` for a list of supported cipher suites.
+
+For example:
+
+.. code-block:: yaml
 
   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
 
+Reload certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Optionally you can reload certificates with ``reload_interval``, which specifies the duration after which the certificate will be reloaded. 
+
+* If not set, certificates are never reloaded. 
+* Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+
+.. _collector-common-config-tls-client:
+
+Configure TLS clients 
+=============================================================================================
+
+To configure TLS clients in :ref:`exporters <otel-components-exporters>` use the settings in the previous section.
+
+Optionally, you can also configure ``server_name_override``. 
+
+* If set to a non-empty string, it will override the virtual host name of the authority in requests. 
+* This is typically used for testing.
+
+For example:
+
+.. code-block:: yaml
+
+  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
+
+.. _collector-common-config-tls-server:
+
+Configure TLS servers 
+=============================================================================================
+
+To configure TLS servers in :ref:`collector receivers <otel-components-receivers>` use the settings in the previous section.
+
+Optionally, you can also configure:
+
+* ``client_ca_file``. Path to the TLS cert to use by the server to verify a client certificate. This sets the ClientCAs and ClientAuth to ``RequireAndVerifyClientCert`` in the TLS configuration. Refer to :new-page:`https://godoc.org/crypto/tls#Config` for more information.
+
+* ``client_ca_file_reload``. ``false`` by default. Reloads the ClientCAs file when it is modified.
+
+.. note:: These are required for mTLS.
+
+For example:
+
+.. code-block:: yaml
+
+  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
 
+Learn more
+=============================================================================================
 
+For more details on the available settings refer to :new-page:`TLS Configuration Settings <https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configtls>` in OTel's GitHub repo.
diff --git a/gdi/opentelemetry/components/kubelet-stats-receiver.rst b/gdi/opentelemetry/components/kubelet-stats-receiver.rst
@@ -51,7 +51,7 @@ A kubelet runs on a Kubernetes node and has an API server to which the Kubelet s
 
 There are two ways to authenticate, as indicated by the ``auth_type`` field:
 
--  ``tls`` tells the receiver to use TLS for authentication and requires that the ``ca_file``, ``key_file``, and ``cert_file`` fields.
+-  ``tls`` tells the receiver to use TLS for authentication and requires that the ``ca_file``, ``key_file``, and ``cert_file`` fields. See more at :ref:`collector-common-config-tls`.
 -  ``ServiceAccount`` tells this receiver to use the default service account token to authenticate to the kubelet API.
 
 Configure TLS authentication
diff --git a/gdi/opentelemetry/components/otlp-exporter.rst b/gdi/opentelemetry/components/otlp-exporter.rst
@@ -75,7 +75,8 @@ The following settings are required:
 * ``tls``. See :ref:`TLS Configuration Settings <otlp-exporter-settings>` in this document for the full set of available options. 
 
   * By default, ``tls: insecure`` is set to ``true``. 
-  * Mutual TLS (mTLS) is also supported. See more at :new-page:`TLS/mTLS configuration <https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md#tls--mtls-configuration>` in GitHub.
+  * Mutual TLS (mTLS) is also supported. 
+  * See more at :ref:`collector-common-config-tls`.
 
 Configuration examples
 --------------------------------
@@ -102,7 +103,6 @@ By default, gzip compression is enabled. To turn it off, use the following confi
 
 .. code-block:: yaml
 
-
   exporters:
     otlp:
       ...
diff --git a/gdi/opentelemetry/components/otlp-receiver.rst b/gdi/opentelemetry/components/otlp-receiver.rst
