Fix TLS related docs and TLS config name for Server side settings (#4063

)

commit 4607209
Author: Min Xia <[email protected]>
Date:   Thu Sep 16 13:33:52 2021 -0700

    Do not squash `configtls.TLSClientSetting` in `confighttp` and `cnofiggrpc` config

CHANGELOG.md

@@ -8,6 +8,8 @@
 - Remove AttributeMessageType (#4020)
 - Remove `mem-ballast-size-mib`, already deprecated and no-op (#4005).
 - Remove `AttributeHTTPStatusText` const, replaced with `"http.status_text"` (#4015, contrib/#5182).
+- Remove squash on `configtls.TLSClientSetting` and move TLS client configs under `tls` (#4063).
+- Rename TLS server config `*configtls.TLSServerSetting` from `tls_settings` to `tls` (#4063).
 
 ## v0.35.0 Beta
 

config/configauth/README.md

@@ -4,7 +4,7 @@ This module allows server types, such as gRPC and HTTP, to be configured to perf
 
 The currently known authenticators:
 
-- [oidc](../../extension/oidcauthextension)
+- [oidc](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/oidcauthextension)
 
 Examples:
 ```yaml
@@ -22,7 +22,7 @@ receivers:
     protocols:
       grpc:
         endpoint: localhost:4318
-        tls_settings:
+        tls:
           cert_file: /tmp/certs/cert.pem
           key_file: /tmp/certs/cert-key.pem
         auth:

config/configgrpc/README.md

@@ -10,14 +10,15 @@ adjusted.
 [Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/README.md)
 leverage client configuration.
 
-Note that client configuration supports TLS configuration, however
-configuration parameters are not defined under `tls_settings` like server
+Note that client configuration supports TLS configuration, the
+configuration parameters are also defined under `tls` like server
 configuration. For more information, see [configtls
 README](../configtls/README.md).
 
 - [`balancer_name`](https://github.com/grpc/grpc-go/blob/master/examples/features/load_balancing/README.md)
 - `compression` (default = gzip): Compression type to use (only gzip is supported today)
 - `endpoint`: Valid value syntax available [here](https://github.com/grpc/grpc/blob/master/doc/naming.md)
+- [`tls`](../configtls/README.md)
 - `headers`: name/value pairs added to the request
 - [`keepalive`](https://godoc.org/google.golang.org/grpc/keepalive#ClientParameters)
   - `permit_without_stream`
@@ -34,6 +35,10 @@ Example:
 exporters:
   otlp:
     endpoint: otelcol2:55690
+    tls:
+      ca_file: ca.pem
+      cert_file: cert.pem
+      key_file: key.pem
     headers:
       test1: "value1"
       "test 2": "value 2"
@@ -60,5 +65,5 @@ see [confignet README](../confignet/README.md).
 - [`max_concurrent_streams`](https://godoc.org/google.golang.org/grpc#MaxConcurrentStreams)
 - [`max_recv_msg_size_mib`](https://godoc.org/google.golang.org/grpc#MaxRecvMsgSize)
 - [`read_buffer_size`](https://godoc.org/google.golang.org/grpc#ReadBufferSize)
-- [`tls_settings`](../configtls/README.md)
+- [`tls`](../configtls/README.md)
 - [`write_buffer_size`](https://godoc.org/google.golang.org/grpc#WriteBufferSize)

config/configgrpc/configgrpc.go

@@ -73,7 +73,7 @@ type GRPCClientSettings struct {
 	Compression string `mapstructure:"compression"`
 
 	// TLSSetting struct exposes TLS client configuration.
-	TLSSetting configtls.TLSClientSetting `mapstructure:",squash"`
+	TLSSetting configtls.TLSClientSetting `mapstructure:"tls,omitempty"`
 
 	// The keepalive parameters for gRPC client. See grpc.WithKeepaliveParams.
 	// (https://godoc.org/google.golang.org/grpc#WithKeepaliveParams).
@@ -134,7 +134,7 @@ type GRPCServerSettings struct {
 
 	// Configures the protocol to use TLS.
 	// The default value is nil, which will cause the protocol to not use TLS.
-	TLSSetting *configtls.TLSServerSetting `mapstructure:"tls_settings,omitempty"`
+	TLSSetting *configtls.TLSServerSetting `mapstructure:"tls,omitempty"`
 
 	// MaxRecvMsgSizeMiB sets the maximum size (in MiB) of messages accepted by the server.
 	MaxRecvMsgSizeMiB uint64 `mapstructure:"max_recv_msg_size_mib"`

config/confighttp/README.md

@@ -9,12 +9,13 @@ receivers or exporters.
 [Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/README.md)
 leverage client configuration.
 
-Note that client configuration supports TLS configuration, however
-configuration parameters are not defined under `tls_settings` like server
+Note that client configuration supports TLS configuration, the
+configuration parameters are also defined under `tls` like server
 configuration. For more information, see [configtls
 README](../configtls/README.md).
 
 - `endpoint`: address:port
+- [`tls`](../configtls/README.md)
 - `headers`: name/value pairs added to the HTTP request headers
 - [`read_buffer_size`](https://golang.org/pkg/net/http/#Transport)
 - [`timeout`](https://golang.org/pkg/net/http/#Client)
@@ -26,6 +27,10 @@ Example:
 exporter:
   otlp:
     endpoint: otelcol2:55690
+    tls:
+      ca_file: ca.pem
+      cert_file: cert.pem
+      key_file: key.pem
     headers:
       test1: "value1"
       "test 2": "value 2"
@@ -44,7 +49,7 @@ leverage server configuration.
   `Content-Type`, `X-Requested-With`. `Origin` is also always
   added to the list. A wildcard (`*`) can be used to match any header.
 - `endpoint`: Valid value syntax available [here](https://github.com/grpc/grpc/blob/master/doc/naming.md)
-- [`tls_settings`](../configtls/README.md)
+- [`tls`](../configtls/README.md)
 
 Example:
 

config/confighttp/confighttp.go

@@ -38,7 +38,7 @@ type HTTPClientSettings struct {
 	Endpoint string `mapstructure:"endpoint"`
 
 	// TLSSetting struct exposes TLS client configuration.
-	TLSSetting configtls.TLSClientSetting `mapstructure:",squash"`
+	TLSSetting configtls.TLSClientSetting `mapstructure:"tls,omitempty"`
 
 	// ReadBufferSize for HTTP client. See http.Transport.ReadBufferSize.
 	ReadBufferSize int `mapstructure:"read_buffer_size"`
@@ -140,7 +140,7 @@ type HTTPServerSettings struct {
 	Endpoint string `mapstructure:"endpoint"`
 
 	// TLSSetting struct exposes TLS client configuration.
-	TLSSetting *configtls.TLSServerSetting `mapstructure:"tls_settings, omitempty"`
+	TLSSetting *configtls.TLSServerSetting `mapstructure:"tls, omitempty"`
 
 	// CorsOrigins are the allowed CORS origins for HTTP/JSON requests to grpc-gateway adapter
 	// for the OTLP receiver. See github.com/rs/cors

config/configtls/README.md

@@ -48,8 +48,8 @@ See below for examples.
 [Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/README.md)
 leverage client configuration.
 
-Note that client configuration supports TLS configuration, however
-configuration parameters are not defined under `tls_settings` like server
+Note that client configuration supports TLS configuration, the
+configuration parameters are also defined under `tls` like server
 configuration. For more information, see [configtls
 README](../configtls/README.md).
 
@@ -66,11 +66,12 @@ exporters:
   otlp:
     endpoint: myserver.local:55690
     insecure: false
-    ca_file: server.crt
-    cert_file: client.crt
-    key_file: client.key
-    min_version: "1.1"
-    max_version: "1.2"
+    tls:
+      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
     insecure: true
@@ -101,14 +102,14 @@ receivers:
     protocols:
       grpc:
         endpoint: mysite.local:55690
-        tls_settings:
+        tls:
           cert_file: server.crt
           key_file: server.key
   otlp/mtls:
     protocols:
       grpc:
         endpoint: mysite.local:55690
-        tls_settings:
+        tls:
           client_ca_file: client.pem
           cert_file: server.crt
           key_file: server.key

exporter/otlpexporter/testdata/config.yaml

@@ -12,7 +12,8 @@ exporters:
   otlp/2:
     endpoint: "1.2.3.4:1234"
     compression: "on"
-    ca_file: /var/lib/mycert.pem
+    tls:
+      ca_file: /var/lib/mycert.pem
     timeout: 10s
     sending_queue:
       enabled: true

exporter/otlphttpexporter/testdata/config.yaml

@@ -8,10 +8,11 @@ exporters:
   otlphttp:
   otlphttp/2:
     endpoint: "https://1.2.3.4:1234"
-    insecure: true
-    ca_file: /var/lib/mycert.pem
-    cert_file: certfile
-    key_file: keyfile
+    tls:
+      ca_file: /var/lib/mycert.pem
+      cert_file: certfile
+      key_file: keyfile
+      insecure: true
     timeout: 10s
     read_buffer_size: 123
     write_buffer_size: 345

receiver/otlpreceiver/config.md

@@ -22,7 +22,7 @@ Config defines configuration for OTLP receiver.
 | ---- | ---- | ------- | ---- |
 | endpoint |string| 0.0.0.0:4317 | 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 |string| tcp | Transport to use. Known protocols are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only), "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4" (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and "unixpacket".  |
-| tls_settings |[configtls-TLSServerSetting](#configtls-TLSServerSetting)| <no value> | Configures the protocol to use TLS. The default value is nil, which will cause the protocol to not use TLS.  |
+| tls |[configtls-TLSServerSetting](#configtls-TLSServerSetting)| <no value> | Configures the protocol to use TLS. The default value is nil, which will cause the protocol to not use TLS.  |
 | max_recv_msg_size_mib |uint64| <no value> | MaxRecvMsgSizeMiB sets the maximum size (in MiB) of messages accepted by the server.  |
 | max_concurrent_streams |uint32| <no value> | MaxConcurrentStreams sets the limit on the number of concurrent streams to each ServerTransport. It has effect only for streaming RPCs.  |
 | read_buffer_size |int| 524288 | ReadBufferSize for gRPC server. See grpc.ReadBufferSize (https://godoc.org/google.golang.org/grpc#ReadBufferSize).  |
@@ -74,7 +74,7 @@ Config defines configuration for OTLP receiver.
 | Name | Type | Default | Docs |
 | ---- | ---- | ------- | ---- |
 | endpoint |string| 0.0.0.0:4318 | Endpoint configures the listening address for the server.  |
-| tls_settings |[configtls-TLSServerSetting](#configtls-TLSServerSetting)| <no value> | TLSSetting struct exposes TLS client configuration.  |
+| tls |[configtls-TLSServerSetting](#configtls-TLSServerSetting)| <no value> | TLSSetting struct exposes TLS client configuration.  |
 | cors_allowed_origins |[]string| <no value> | CorsOrigins are the allowed CORS origins for HTTP/JSON requests to grpc-gateway adapter for the OTLP receiver. See github.com/rs/cors An empty list means that CORS is not enabled at all. A wildcard (*) can be used to match any origin or one or more characters of an origin.  |
 | cors_allowed_headers |[]string| <no value> | CorsHeaders are the allowed CORS headers for HTTP/JSON requests to grpc-gateway adapter for the OTLP receiver. See github.com/rs/cors CORS needs to be enabled first by providing a non-empty list in CorsOrigins A wildcard (*) can be used to match any header.  |
 

receiver/otlpreceiver/testdata/config.yaml

@@ -54,11 +54,11 @@ receivers:
   otlp/tlscredentials:
     protocols:
       grpc:
-        tls_settings:
+        tls:
           cert_file: test.crt
           key_file: test.key
       http:
-        tls_settings:
+        tls:
           cert_file: test.crt
           key_file: test.key
   # The following entry demonstrates how to specify a Unix Domain Socket for the server.