Skip to content

Commit 5f860db

Browse files
Vanshul97bogdandrutucodeboten
authored andcommitted
[chore] Clarify TLS docs: mTLS is optional, not mandatory (#15143)
## Summary Rewords the TLS configuration documentation to clarify that mutual TLS (mTLS) is optional and standard TLS works by default. Fixes #13757 ## Problem The current documentation reads as if `cert_file` and `key_file` are always required ("the following parameters are also required"), which leads readers to believe that mTLS is mandatory. This causes confusion for users who only need standard TLS (server certificate verification). ## Changes - Clarified upfront that standard TLS works by default with system root CAs - Explicitly stated mTLS is optional - Reworded "the following parameters are also required" to "the following certificate parameters can be configured" - Clarified when `cert_file`/`key_file` are actually needed (server: always for TLS, client: only for mTLS) - Moved `ca_file` before `cert_file`/`key_file` since it's the more commonly needed parameter ## Test Plan - [x] Documentation-only change Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com> Co-authored-by: Alex Boten <223565+codeboten@users.noreply.github.com>
1 parent bd1b758 commit 5f860db

1 file changed

Lines changed: 19 additions & 16 deletions

File tree

config/configtls/README.md

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,18 @@ Crypto TLS exposes a [variety of settings](https://godoc.org/crypto/tls).
44
Several of these settings are available for configuration within individual
55
receivers or exporters.
66

7-
Note that mutual TLS (mTLS) is also supported.
7+
Note that mutual TLS (mTLS) is also supported as an optional enhancement on
8+
top of standard TLS.
89

910
## TLS / mTLS Configuration
1011

11-
By default, TLS is enabled:
12+
By default, TLS is enabled with server certificate verification using the
13+
system root CAs. No additional configuration is needed for standard TLS.
14+
Mutual TLS (mTLS), where both client and server present certificates, is
15+
optional and requires additional configuration (see examples below).
1216

13-
- `insecure` (default = false): whether to enable client transport security for
14-
the exporter's HTTPs or gRPC connection. See
17+
- `insecure` (default = false): whether to disable transport security entirely.
18+
When set to true, no TLS is used at all. See
1519
[grpc.WithInsecure()](https://godoc.org/google.golang.org/grpc#WithInsecure)
1620
for gRPC.
1721
- `curve_preferences` (default = []): specify your curve preferences that will
@@ -21,23 +25,22 @@ By default, TLS is enabled:
2125
- P256
2226
- P384
2327

24-
As a result, the following parameters are also required:
28+
The following certificate parameters can be configured:
2529

26-
- `cert_file`: Path to the TLS cert to use for TLS required connections. Should
27-
only be used if `insecure` is set to false.
30+
- `ca_file`: Path to the CA cert. For a client this verifies the server
31+
certificate. For a server this verifies client certificates. If empty, the
32+
system root CAs are used.
33+
- `ca_pem`: Alternative to `ca_file`. Provide the CA cert contents as a string instead of a filepath.
34+
35+
- `cert_file`: Path to the TLS certificate. For a server this is required to
36+
serve TLS. For a client this is only needed for mTLS (client certificate
37+
authentication).
2838
- `cert_pem`: Alternative to `cert_file`. Provide the certificate contents as a string instead of a filepath.
2939

30-
- `key_file`: Path to the TLS key to use for TLS required connections. Should
31-
only be used if `insecure` is set to false.
40+
- `key_file`: Path to the TLS private key. Must be provided alongside
41+
`cert_file`.
3242
- `key_pem`: Alternative to `key_file`. Provide the key contents as a string instead of a filepath.
3343

34-
A certificate authority may also need to be defined:
35-
36-
- `ca_file`: Path to the CA cert. For a client this verifies the server
37-
certificate. For a server this verifies client certificates. If empty uses
38-
system root CA. Should only be used if `insecure` is set to false.
39-
- `ca_pem`: Alternative to `ca_file`. Provide the CA cert contents as a string instead of a filepath.
40-
4144
You can also combine defining a certificate authority with the system certificate authorities.
4245

4346
- `include_system_ca_certs_pool` (default = false): whether to load the system certificate authorities pool

0 commit comments

Comments
 (0)