From df6652bb0dee759caf2ac707e0639057548c3fec Mon Sep 17 00:00:00 2001
From: Manfred Moser <manfred@simpligility.ca>
Date: Wed, 23 Oct 2024 10:09:54 -0700
Subject: [PATCH] Update docs for internal communication

Add properties to HTTP server props page including HTTP/2 details.
---
 .../sphinx/admin/properties-http-server.md    | 31 +++++++++++++++++++
 .../sphinx/security/internal-communication.md | 19 ++++++++----
 2 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/docs/src/main/sphinx/admin/properties-http-server.md b/docs/src/main/sphinx/admin/properties-http-server.md
index d18a584e9f30b..6a36c205564f2 100644
--- a/docs/src/main/sphinx/admin/properties-http-server.md
+++ b/docs/src/main/sphinx/admin/properties-http-server.md
@@ -159,3 +159,34 @@ Configuration properties for the `PASSWORD` authentication types
 ### `http-server.log.*`
 
 Configuration properties for [](/admin/properties-logging).
+
+(props-internal-communication)
+## Internal communication
+
+The following properties are used for configuring the [internal
+communication](/security/internal-communication) between all
+[nodes](trino-concept-node) of a Trino cluster.
+
+### `internal-communication.shared-secret`
+
+- **Type:** [](prop-type-string)
+
+The string to use as secret that only the coordinators and workers in a specific
+cluster share and use to authenticate within the cluster. See
+[](internal-secret) for details.
+
+### `internal-communication.http2.enabled`
+
+- **Type:** [](prop-type-boolean)
+- **Default value:** `true`
+
+Enable use of the HTTP/2 protocol for internal communication for enhanced
+scalability compared to HTTP/1.1. Only turn this feature off, if you encounter
+issues with HTTP/2 usage within the cluster in your deployment.
+
+### `internal-communication.https.required`
+
+- **Type:** [](prop-type-boolean)
+- **Default value:** `false`
+
+Enable the use of [SSL/TLS for all internal communication](internal-tls).
diff --git a/docs/src/main/sphinx/security/internal-communication.md b/docs/src/main/sphinx/security/internal-communication.md
index e2847000befed..2bec797f5767e 100644
--- a/docs/src/main/sphinx/security/internal-communication.md
+++ b/docs/src/main/sphinx/security/internal-communication.md
@@ -4,15 +4,16 @@ The Trino cluster can be configured to use secured communication with internal
 authentication of the nodes in the cluster, and to optionally use added security
 with {ref}`TLS <glossTLS>`.
 
+(internal-secret)=
 ## Configure shared secret
 
-Configure a shared secret to authenticate all communication between nodes of the
-cluster. Use this configuration under the following conditions:
+You must configure a shared secret to authenticate all communication between
+nodes of the cluster in the following scenarios:
 
-- When opting to configure [internal TLS encryption](internal-tls)
-  between nodes of the cluster
-- When using any {doc}`external authentication <authentication-types>` method
-  between clients and the coordinator
+- When using [any authentication](authentication-types) between clients and the
+  coordinator.
+- When using [internal TLS encryption](internal-tls) between all nodes of the
+  cluster.
 
 Set the shared secret to the same value in {ref}`config.properties
 <config-properties>` on all nodes of the cluster:
@@ -122,6 +123,12 @@ window functions, which require repartitioning), the performance impact can be
 considerable. The slowdown may vary from 10% to even 100%+, depending on the network
 traffic and the CPU utilization.
 
+:::{note}
+By default, internal communication with SSL/TLS enabled uses HTTP/2 for
+increased scalability. You can turn off this feature with
+`internal-communication.http2.enabled=false`.
+:::
+
 (internal-performance)=
 ### Advanced performance tuning