Upgrade notes and docs

docs/upgrade.md

@@ -87,6 +87,29 @@ process, for example:
     wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
     dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
     ```
+# Upgrading to v1.79.0
+
+## Changes to federation sender config
+
+_This notice only applies to deployments using multiple workers. Deployments
+not using workers are not affected._
+
+From Synapse 1.79, only [federation senders](
+https://matrix-org.github.io/synapse/release-v1.79/usage/configuration/config_documentation.html#federation_sender_instances
+) will make outgoing key requests to homeservers and [trusted key servers](
+https://matrix-org.github.io/synapse/release-v1.79/usage/configuration/config_documentation.html#trusted_key_servers
+). This will make it easier for server operators to reason about how Synapse
+communicates with the wider federation. As a consequence, all other workers now 
+ask federation senders to fetch keys on their behalf.
+
+To facilitate this,
+
+- federation senders must now be present in the [instance map](
+  https://matrix-org.github.io/synapse/release-v1.79/usage/configuration/config_documentation.html#instance_map
+  ), and
+- federation senders must now run an [http listener](
+  https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#listeners 
+  ) which includes the `replication` resource.
 
 # Upgrading to v1.78.0
 

docs/usage/configuration/config_documentation.md

@@ -3811,7 +3811,7 @@ send_federation: false
 ### `federation_sender_instances`
 
 It is possible to scale the processes that handle sending outbound federation requests
-by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
+by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding its [`worker_name`](#worker_name) to
 a `federation_sender_instances` map. Doing so will remove handling of this function from
 the main process. Multiple workers can be added to this map, in which case the work is
 balanced across them.
@@ -3821,6 +3821,10 @@ sending, and if changed all federation sender workers must be stopped at the sam
 and then started, to ensure that all instances are running with the same config (otherwise
 events may be dropped).
 
+Federation senders should have a replication [`http` listener](#listeners)
+configured, and should be present in the [`instance_map`](#instance_map)
+so that other workers can make internal http requests to the federation senders.
+
 Example configuration for a single worker:
 ```yaml
 federation_sender_instances:
@@ -3832,6 +3836,10 @@ federation_sender_instances:
   - federation_sender1
   - federation_sender2
 ```
+
+_Changed in Synapse 1.79: Federation senders should now have an http listener
+listening for `replication`, and should be present in the `instance_map`._
+
 ---
 ### `instance_map`
 

docs/workers.md

@@ -590,10 +590,18 @@ It is likely this option will be deprecated in the future and not recommended fo
 new installations. Instead, [use `synapse.app.generic_worker` with the `federation_sender_instances`](usage/configuration/config_documentation.md#federation_sender_instances).
 
 Handles sending federation traffic to other servers. Doesn't handle any
-REST endpoints itself, but you should set
+client-facing REST endpoints itself, but you should set
 [`send_federation: false`](usage/configuration/config_documentation.md#send_federation)
 in the shared configuration file to stop the main synapse sending this traffic.
 
+Federation senders should have a replication [`http` listener](
+usage/configuration/config_documentation.md#listeners
+) configured, and
+should be present in the [`instance_map`](
+usage/configuration/config_documentation.md#instance_map
+) so that other workers can make internal
+http requests to the federation senders.
+
 If running multiple federation senders then you must list each
 instance in the
 [`federation_sender_instances`](usage/configuration/config_documentation.md#federation_sender_instances)
@@ -607,6 +615,13 @@ send_federation: false
 federation_sender_instances:
     - federation_sender1
     - federation_sender2
+instance_map:
+    - federation_sender1:
+        - host: localhost
+        - port: 1001
+    - federation_sender2:
+         - host: localhost
+         - port: 1002
 ```
 
 An example for a federation sender instance:
@@ -615,6 +630,9 @@ An example for a federation sender instance:
 {{#include systemd-with-workers/workers/federation_sender.yaml}}
 ```
 
+_Changed in Synapse 1.79: Federation senders should now have an http listener
+listening for `replication`, and should be present in the `instance_map`._
+
 ### `synapse.app.media_repository`
 
 Handles the media repository. It can handle all endpoints starting with: