document TLS termination and subgraph override (#3436)

Fix #3100

TLS termination was added in #2614 but never documented, and subgrpah
certificate override was added in #2008 but the documentation was
missing some details on self signed certificates.

Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

.changesets/docs_geal_document_tls.md

@@ -0,0 +1,5 @@
+### document TLS termination and subgraph override ([Issue #3100](https://github.com/apollographql/router/issues/3100))
+
+TLS termination was added in #2614 but never documented, and subgraph certificate override was added in #2008 but the documentation was missing some details on self signed certificates.
+
+By [@Geal](https://github.com/Geal) in https://github.com/apollographql/router/pull/3436

docs/source/configuration/overview.mdx

@@ -514,7 +514,49 @@ See [Tracing in the Apollo Router](./tracing/).
 
 ### TLS
 
-TLS connections to subgraphs are verified using the list of certificate authorities provided by the system. You can override this list with a combination of global and per-subgraph settings:
+The Apollo Router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with `https://`.
+
+TLS support is configured in the `tls` section, under the `supergraph` key for the client side, and the `subgraph` key for the subgraph side, with configuration possible for all subgraphs and overriding per subgraph.
+
+The list of supported TLS versions and algorithms is static, it cannot be configured.
+
+Supported TLS versions:
+* TLS 1.2
+* TLS 1.3
+
+Supported cipher suites:
+* TLS13_AES_256_GCM_SHA384
+* TLS13_AES_128_GCM_SHA256
+* TLS13_CHACHA20_POLY1305_SHA256
+* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
+* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
+* TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
+* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
+* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
+* TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
+
+Supported key exchange groups:
+* X25519
+* SECP256R1
+* SECP384R1
+
+#### TLS termination
+
+Clients can connect to the router directly over HTTPS, without terminating TLS in an intermediary. You can  configure this in the `tls` configuration section:
+
+```yaml
+tls:
+  supergraph:
+    certificate: ${file./path/to/certificate.pem}
+    certificate_chain: ${file./path/to/certificate_chain.pem}
+    key: ${file./path/to/key.pem}
+```
+
+The router expects the file referenced in the `certificate_chain` value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).
+
+#### Overriding certificate authorities for subgraphs
+
+The router verifies TLS connections to subgraphs using the list of certificate authorities the system provides. You can override this list with a combination of global and per-subgraph settings:
 
 ```yaml title="router.yaml"
 tls:
@@ -528,6 +570,32 @@ tls:
         certificate_authorities: "${file./path/to/product_ca.crt}"
 ```
 
+The router expects the file referenced in the `certificate_chain` value to be a combination of several PEM certificates concatenated together into a single file (as is commonplace with Apache TLS configuration).
+
+You can only configure these certificates via the router's configuration since using `SSL_CERT_FILE` also overrides certificates for sending telemetry and communicating with Apollo Uplink.
+
+> **Note**: If the subgraph is presenting a self-signed certificate, it must be generated with the proper file extension and with `basicConstraints` disabled.
+> You can generate it with the following command line command from a certificate signing request, in this example, `server.csr`:
+
+```
+openssl x509 -req -in server.csr -signkey server.key -out server.crt -extfile v3.ext
+```
+
+You can generate a `v3.ext` extension file like so:
+
+```
+subjectKeyIdentifier   = hash
+authorityKeyIdentifier = keyid:always,issuer:always
+# this has to be disabled
+# basicConstraints       = CA:TRUE
+keyUsage               = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign
+subjectAltName         = DNS:local.apollo.dev
+issuerAltName          = issuer:copy
+```
+
+> Make sure to change the `subjectAltName` field to the subgraph's name.
+This produces the file as `server.crt` which can be used in `certificate_authorities`.
+
 ### Request limits
 
 > **Request limits are currently in [preview](/resources/product-launch-stages#preview).**