matrix-tuwunel: add labels to expose the Synapse-compatible admin API

Tuwunel serves the Synapse administration API under /_synapse/admin,
but the role only routed /_matrix, so admin dashboards and moderation
bots could not reach it. Add public and internal Traefik label groups
mirroring the matrix-synapse role, and enable them automatically when
Ketesa, Element Admin, or Draupnir is installed.

docs/configuring-playbook-ketesa.md

@@ -41,6 +41,7 @@ matrix_ketesa_enabled: true
 
 - for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
 - for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
+- for [Tuwunel](./configuring-playbook-tuwunel.md): `matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true`
 
 By default, Ketesa installation will be [restricted to only work with one homeserver](https://github.com/etkecc/ketesa/blob/main/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_ketesa_config_restrictBaseUrl` variable.
 

docs/configuring-playbook-tuwunel.md

@@ -180,6 +180,22 @@ When enabled, rooms with a valid `m.room.policy` state event have outgoing event
 
 The role sets `default_room_version: '12'`, so newly created rooms default to Matrix [room version 12](https://github.com/matrix-org/matrix-spec-proposals/pull/4289) ("Hydra"). Override `matrix_tuwunel_config_default_room_version` if you need an earlier version for client compatibility.
 
+### Exposing the Administration API
+
+Tuwunel serves a Synapse-compatible Administration API under the `/_synapse/admin` path, so administration dashboards (such as synapse-admin and ketesa) and moderation bots (such as Draupnir and Meowlnir) work against it. The served endpoints are listed on the [Tuwunel Synapse Admin API page](https://matrix-construct.github.io/tuwunel/development/compliance/synapse-admin.html).
+
+The API is not routed through the reverse proxy by default. Every endpoint requires an administrator access token, but you may still prefer to keep it off the public entrypoint. To reach it only from trusted networks, expose it on the internal Traefik entrypoint:
+
+```yaml
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_enabled: true
+```
+
+To expose it publicly instead (for example, when a dashboard runs in the browser), set:
+
+```yaml
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true
+```
+
 ## Creating the first user account
 
 Unlike Synapse and Dendrite, Tuwunel does not register users from the command line or via the playbook. On first startup it logs a one-time-use registration token to its journal:

group_vars/matrix_servers

@@ -5819,6 +5819,10 @@ matrix_tuwunel_container_labels_traefik_tls_certResolver: "{{ traefik_certResolv
 matrix_tuwunel_container_labels_public_client_root_redirection_enabled: "{{ matrix_tuwunel_container_labels_public_client_root_redirection_url != '' }}"
 matrix_tuwunel_container_labels_public_client_root_redirection_url: "{{ (('https://' if matrix_playbook_ssl_enabled else 'http://') + matrix_server_fqn_element) if matrix_client_element_enabled else '' }}"
 
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: "{{ matrix_ketesa_enabled or matrix_element_admin_enabled }}"
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_enabled: "{{ (matrix_bot_draupnir_enabled and matrix_bot_draupnir_admin_api_enabled) }}"
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
+
 matrix_tuwunel_container_labels_public_federation_api_traefik_hostname: "{{ matrix_server_fqn_matrix_federation }}"
 matrix_tuwunel_container_labels_public_federation_api_traefik_entrypoints: "{{ matrix_federation_traefik_entrypoint_name }}"
 matrix_tuwunel_container_labels_public_federation_api_traefik_tls: "{{ matrix_federation_traefik_entrypoint_tls }}"

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

@@ -106,6 +106,25 @@ matrix_tuwunel_container_labels_public_federation_api_traefik_entrypoints: ''
 matrix_tuwunel_container_labels_public_federation_api_traefik_tls: true
 matrix_tuwunel_container_labels_public_federation_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
 
+# Controls whether labels will be added that expose the Synapse-compatible Administration API (`/_synapse/admin`) on a public Traefik entrypoint.
+# Tuwunel serves this API so that administration dashboards (synapse-admin, ketesa) and moderation bots (Draupnir, Meowlnir) work against it.
+# Every endpoint requires an administrator access token. It is disabled by default; you may prefer to expose it only on the internal entrypoint below.
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: false
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_hostname: "{{ matrix_tuwunel_hostname }}"
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_path_prefix: /_synapse/admin
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_rule: "Host(`{{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_path_prefix }}`)"
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_priority: 0
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_tuwunel_container_labels_traefik_entrypoints }}"
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_tls: "{{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_entrypoints != 'web' }}"
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added that expose the Synapse-compatible Administration API (`/_synapse/admin`) on the internal Traefik entrypoint.
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_enabled: false
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_path_prefix: /_synapse/admin
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_rule: "PathPrefix(`{{ matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_path_prefix }}`)"
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_priority: 0
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: ""
+
 # Additional Docker container labels (multiline string) appended verbatim to the label file.
 # See `../templates/labels.j2`.
 matrix_tuwunel_container_labels_additional_labels: ''

roles/custom/matrix-tuwunel/templates/labels.j2

@@ -136,6 +136,59 @@ traefik.http.routers.matrix-tuwunel-public-federation-api.tls.certResolver={{ ma
 {% endif %}
 
 
+{% if matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled %}
+############################################################
+#                                                          #
+# Public Synapse Admin API (/_synapse/admin)               #
+#                                                          #
+############################################################
+
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.rule={{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_rule }}
+
+{% if matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.priority={{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.service=matrix-tuwunel
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.entrypoints={{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_entrypoints }}
+
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.tls={{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_tls | to_json }}
+{% if matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_tls %}
+traefik.http.routers.matrix-tuwunel-public-client-synapse-admin-api.tls.certResolver={{ matrix_tuwunel_container_labels_public_client_synapse_admin_api_traefik_tls_certResolver }}
+{% endif %}
+
+############################################################
+#                                                          #
+# /Public Synapse Admin API (/_synapse/admin)              #
+#                                                          #
+############################################################
+{% endif %}
+
+
+{% if matrix_tuwunel_container_labels_internal_client_synapse_admin_api_enabled %}
+############################################################
+#                                                          #
+# Internal Synapse Admin API (/_synapse/admin)             #
+#                                                          #
+############################################################
+
+traefik.http.routers.matrix-tuwunel-internal-client-synapse-admin-api.rule={{ matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_rule }}
+
+{% if matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-tuwunel-internal-client-synapse-admin-api.priority={{ matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-tuwunel-internal-client-synapse-admin-api.service=matrix-tuwunel
+traefik.http.routers.matrix-tuwunel-internal-client-synapse-admin-api.entrypoints={{ matrix_tuwunel_container_labels_internal_client_synapse_admin_api_traefik_entrypoints }}
+
+############################################################
+#                                                          #
+# /Internal Synapse Admin API (/_synapse/admin)            #
+#                                                          #
+############################################################
+{% endif %}
+
+
 {% endif %}
 
 {{ matrix_tuwunel_container_labels_additional_labels }}