Merge pull request #2262 from splunk/urbiz-=D6367-collector-common-congif

[6367]: Collector common config

Author: aurbiztondo-splunk

_includes/gdi/collector-common-options.rst

@@ -0,0 +1,6 @@
+The Splunk Distribution of the OpenTelemetry Collector has the following configuration options than can be used by several :ref:`otel-components`.
+
+* :ref:`collector-common-config-auth`
+* :ref:`collector-common-config-grcp`
+* :ref:`collector-common-config-net`
+* :ref:`collector-common-config-tls`

gdi/opentelemetry/collector-common-config.rst

@@ -0,0 +1,22 @@
+.. _collector-common-config:
+
+****************************************************************
+Common configuration options
+****************************************************************
+
+.. meta::
+      :description: Learn how to perform common actions with the Collector.
+
+.. toctree::
+    :maxdepth: 4
+    :titlesonly:
+    :hidden:
+
+    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-tls.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.  
+
+.. include:: /_includes/gdi/collector-common-options.rst

gdi/opentelemetry/collector-kubernetes/collector-kubernetes-intro.rst

@@ -64,6 +64,8 @@ To configure the Collector, including adding additional components or activating
 * :ref:`kubernetes-config-logs`
 * :ref:`otel-kubernetes-config-advanced`
 
+.. include:: /_includes/gdi/collector-common-options.rst
+
 .. raw:: html
 
   <embed>

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

@@ -0,0 +1,73 @@
+.. _collector-common-config-auth:
+
+*********************************************************************************
+Configure authentication 
+*********************************************************************************
+
+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
+
+* 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>`
+  * Bearer Token extension
+  * :ref:`oauth2client-extension`
+  * Sigv4 extension
+
+.. 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
+=============================================================================================
+
+See the following example covering different auth options: 
+
+.. code-block:: yaml
+
+   extensions:
+      oidc:
+         # see the blog post on securing the otelcol for information
+         # on how to setup an OIDC server and how to generate the TLS certs
+         # required for this example
+         # https://medium.com/opentelemetry/securing-your-opentelemetry-collector-1a4f9fa5bd6f
+         issuer_url: http://localhost:8080/auth/realms/opentelemetry
+         audience: account
+
+   oauth2client:
+      client_id: someclientid
+      client_secret: someclientsecret
+      token_url: https://example.com/oauth2/default/v1/token
+      scopes: ["api.metrics"]
+      # tls settings for the token client
+      tls:
+         insecure: true
+         ca_file: /var/lib/mycert.pem
+         cert_file: certfile
+         key_file: keyfile
+      # timeout for the token client
+      timeout: 2s
+
+   receivers:
+      otlp/with_auth:
+         protocols:
+            grpc:
+               endpoint: localhost:4318
+               tls:
+                  cert_file: /tmp/certs/cert.pem
+                  key_file: /tmp/certs/cert-key.pem
+               auth:
+                  ## oidc is the extension name to use as the authenticator for this receiver
+                  authenticator: oidc
+
+      otlphttp/withauth:
+         endpoint: http://localhost:9000
+         auth:
+            authenticator: oauth2client
+
+
+

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

@@ -0,0 +1,86 @@
+.. _collector-common-config-grcp:
+
+*********************************************************************************
+Configure gRCP 
+*********************************************************************************
+
+gRPC exposes a variety of settings you can adjust within individual receivers or exporters of the Collector. 
+
+.. note:: 
+   
+   To configure transport, see :ref:`collector-common-config-net`.
+
+Configure gRCP clients 
+=============================================================================================
+
+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:
+
+.. 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"
+
+Configure gRCP servers 
+=============================================================================================
+
+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``
+
+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>`

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

@@ -0,0 +1,37 @@
+.. _collector-common-config-net:
+
+*********************************************************************************
+Configure network settings
+*********************************************************************************
+
+:ref:`Collector receivers <otel-components-receivers>` leverage network configuration to set connection and transport information.
+
+You can configure the following network settings:
+
+* ``endpoint``. Configures the address for this network connection. 
+
+  * For TCP and UDP networks, the address has the form ``"host:port"``. The host must be a literal IP address, or a host name that can be resolved to IP addresses. The port must be a literal port number or a service name. 
+
+  * If the host is a literal IPv6 address it must be enclosed in square brackets, as in ``"[2001:db8::1]:80"`` or ``"[fe80::1%zone]:80"``. The zone specifies the scope of the literal IPv6 address as defined in RFC 4007.
+
+* ``transport``. You can use the following protocols:
+
+  * "tcp"
+  * "tcp4" (IPv4-only)
+  * "tcp6" (IPv6-only)
+  * "udp"
+  * "udp4" (IPv4-only)
+  * "udp6" (IPv6-only)
+  * "ip"
+  * "ip4" (IPv4-only)
+  * "ip6" (IPv6-only)
+  * "unix"
+  * "unixgram"
+  * "unixpacket"
+
+* ``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.
+
+
+