Deprecate direct usage of devture_traefik_additional_entrypoints_auto

CHANGELOG.md

@@ -1,3 +1,52 @@
+# 2024-01-14
+
+## (Backward Compatibility) Configuration changes required for people fronting the integrated reverse-proxy webserver with another reverse-proxy
+
+If you're on the default setup (using the Traefik reverse-proxy as installed by the playbook), you don't need to do anything.
+
+People who are [Fronting the integrated Traefik reverse-proxy webserver with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), as per our previous instructions are redefining `devture_traefik_additional_entrypoints_auto` in their `vars.yml` configuration.
+
+Such a full variable redefinion is intrustive, because it prevents the playbook from injecting additional entrypoints into the Traefik webserver. In the future, the playbook may have a need to do so.
+
+For this reason, we no longer recommend completely redefining `devture_traefik_additional_entrypoints_auto`.
+The playbook now defines [various `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_*` variables in the `defaults/main.yml` file](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/custom/matrix-base/defaults/main.yml) of the `matrix-base` role which can be used as a safer alternative to `devture_traefik_additional_entrypoints_auto`.
+
+Adapt your configuration as seen below:
+
+```diff
+-devture_traefik_additional_entrypoints_auto:
+-  - name: matrix-federation
+-    port: 8449
+-    host_bind_port: '127.0.0.1:8449'
+-    config: {}
+-    # If your reverse-proxy runs on another machine, remove the config above and use this config instead:
+-    # config:
+-    #   forwardedHeaders:
+-    #     insecure: true
+-    #     # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
++# Uncomment and tweak the variable below if the name of your federation entrypoint is different
++# than the default value (matrix-federation).
++# matrix_federation_traefik_entrypoint: matrix-federation
++
++# Uncomment and tweak the variable below if you really wish to change the internal port number
++# that the federation endpoint uses. Changing it is generally not necessary.
++# Usually, changing `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` below is enough.
++#matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port: 8449
++
++matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: 127.0.0.1:8449
++
++# Adapt the variable below based on where your reverse-proxy runs:
++# - if it's on the Matrix server: keep `forwardedHeaders` and `insecure: true` as is
++# - if it's on another machine: remove `forwardedHeaders` and `insecure: true` and enable/configure `trustedIPs`
++matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
++  forwardedHeaders:
++    insecure: true
++  # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
+```
+
+Also, feel free to read the [Fronting the integrated Traefik reverse-proxy webserver with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) documentation section again for additional details.
+
+
 # 2024-01-13
 
 ## matrix-reminder-bot update with more secure (backward-incompatible) default settings

docs/configuring-playbook-own-webserver.md

@@ -140,25 +140,28 @@ devture_traefik_container_web_host_bind_port: '127.0.0.1:81'
 
 # We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from
 # a reverse-proxy running on the local machine is safe enough.
+# If you're publishing the port (`devture_traefik_container_web_host_bind_port` above) to a public network interface:
+# - remove the `devture_traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition below
+# - uncomment and adjust the `devture_traefik_config_entrypoint_web_forwardedHeaders_trustedIPs` line below
 devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true
-
-# Or, if you're publishing the port (`devture_traefik_container_web_host_bind_port` above) to a public network interfaces:
-# - remove the `devture_traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition above
-# - uncomment and adjust the line below
 # devture_traefik_config_entrypoint_web_forwardedHeaders_trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
 
-# Likewise (to `devture_traefik_container_web_host_bind_port` above),
-# if your reverse-proxy runs on another machine, consider changing the `host_bind_port` setting below.
-devture_traefik_additional_entrypoints_auto:
-  - name: matrix-federation
-    port: 8449
-    host_bind_port: '127.0.0.1:8449'
-    config: {}
-    # If your reverse-proxy runs on another machine, remove the config above and use this config instead:
-    # config:
-    #   forwardedHeaders:
-    #     insecure: true
-    #     # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
+# Expose the federation entrypoint on a custom port (other than port 8448, which is normally used publicly).
+#
+# We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from
+# a reverse-proxy running on the local machine is safe enough.
+#
+# If your reverse-proxy runs on another machine, consider:
+# - using `0.0.0.0:8449`, just `8449` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:8449` below
+# - adjusting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom` (below) - removing `insecure: true` and enabling/configuring `trustedIPs`
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: 127.0.0.1:8449
+
+# Depending on the value of `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` above,
+# this may need to be reconfigured. See the comments above.
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
+  forwardedHeaders:
+    insecure: true
+  # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
 ```
 
 For an example where the playbook's Traefik reverse-proxy is fronted by another reverse-proxy running on the same server, see [Nginx reverse-proxy fronting the playbook's Traefik](../examples/nginx/README.md) or [Caddy reverse-proxy fronting the playbook's Traefik](../examples/caddy2/README.md).

group_vars/matrix_servers

@@ -31,6 +31,9 @@ matrix_playbook_ssl_retrieval_method: "{{ 'lets-encrypt' if devture_traefik_cert
 
 matrix_playbook_ssl_enabled: "{{ matrix_playbook_ssl_retrieval_method in ['lets-encrypt', 'self-signed', 'manually-managed'] }}"
 
+# A separate Matrix Federation entrypoint is always enabled, unless the federation port matches one of the ports for existing (default) entrypoints
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled: "{{ matrix_federation_public_port not in [devture_traefik_config_entrypoint_web_port, devture_traefik_config_entrypoint_web_secure_port] }}"
+
 ########################################################################
 #                                                                      #
 # /Playbook                                                            #
@@ -4489,15 +4492,9 @@ devture_traefik_base_path: "{{ matrix_base_data_path }}/traefik"
 devture_traefik_uid: "{{ matrix_user_uid }}"
 devture_traefik_gid: "{{ matrix_user_gid }}"
 
-devture_traefik_federation_entrypoint:
-  name: matrix-federation
-  port: "{{ matrix_federation_public_port }}"
-  host_bind_port: "{{ matrix_federation_public_port }}"
-  config: {}
-
 devture_traefik_additional_entrypoints_auto: |
   {{
-    ([devture_traefik_federation_entrypoint] if (matrix_federation_public_port != devture_traefik_config_entrypoint_web_port) and (matrix_federation_public_port != devture_traefik_config_entrypoint_web_secure_port) else [])
+    ([matrix_playbook_public_matrix_federation_api_traefik_entrypoint_definition] if matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled else [])
   }}
 
 devture_traefik_additional_domains_to_obtain_certificates_for: "{{ matrix_ssl_additional_domains_to_obtain_certificates_for }}"

roles/custom/matrix-base/defaults/main.yml

@@ -108,6 +108,7 @@ matrix_server_fqn_rageshake: "rageshake.{{ matrix_domain }}"
 matrix_federation_public_port: 8448
 
 # The name of the Traefik entrypoint for handling Matrix Federation
+# Also see the `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_*` variables.
 matrix_federation_traefik_entrypoint: matrix-federation
 
 # The architecture that your server runs.
@@ -341,6 +342,23 @@ matrix_playbook_reverse_proxy_type: ''
 
 matrix_playbook_service_host_bind_interface_prefix: "{{ '' if matrix_playbook_reverse_proxy_type not in ['other-nginx-non-container', 'other-on-same-host', 'other-on-another-host'] else ('0.0.0.0:' if matrix_playbook_reverse_proxy_type == 'other-on-another-host' else '127.0.0.1:') }}"
 
+# Controls whether to enable an additional Traefik entrypoint for the purpose of serving Matrix Federation.
+# By default, federation is served on a special port (8448), so a separate entrypoint is necessary.
+# Group variables may influence whether this is enabled based on the port number and on the default entrypoints of the Traefik reverse-proxy.
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled: true
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_name: "{{ matrix_federation_traefik_entrypoint }}"
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port: "{{ matrix_federation_public_port }}"
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: "{{ matrix_federation_public_port }}"
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_auto | combine(matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom, recursive=True) }}"
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_auto: {}
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom: {}
+
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_definition:
+  name: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_name }}"
+  port: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_port }}"
+  host_bind_port: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port }}"
+  config: "{{ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config }}"
+
 # Variables to Control which parts of our roles run.
 run_postgres_import: true
 run_postgres_upgrade: true