implemented compose by url, parse, local yaml.

docs/topology.md

@@ -21,9 +21,9 @@ authentik_domain: auth.example.invalid
 
 ## Downstream VMs
 
-Downstream VMs also run Docker. Instead of publishing each application port on
-the host, run Traefik on the VM and attach application containers to the shared
-Docker proxy network.
+Downstream VMs also run Docker and normally run an internal Traefik instance.
+Application containers route through that local Traefik using Docker labels and
+the shared Docker proxy network.
 
 ```yaml
 nbops_roles:
@@ -47,13 +47,85 @@ Traefik labels and join `nbops_proxy_network`, which defaults to `proxy`.
 Only Traefik entrypoints should be exposed on the downstream host firewall. Use
 `traefik_bind_address` to bind those entrypoints to the VM's internal address.
 
+For central edge routing, the edge Traefik uses the file provider to route
+machine-to-machine traffic to each downstream VM's internal Traefik entrypoint.
+The internal Traefik then routes to applications using Docker labels. This keeps
+container discovery local to the VM and gives the edge-to-internal leg a stable
+place for future mTLS.
+
+Edge VM:
+
+```yaml
+nbops_roles:
+  - base
+  - ssh
+  - ufw
+  - updates
+  - docker
+  - traefik
+
+traefik_docker_provider_enabled: false
+traefik_file_provider_enabled: true
+traefik_dynamic_inventory_group: nbops
+```
+
+Downstream VM:
+
+```yaml
+nbops_service_routing_mode: traefik
+nbops_traefik_entrypoint: web
+nbops_traefik_tls: false
+
+traefik_bind_address: "10.0.10.25"
+traefik_publish_entrypoints: true
+
+nbops_traefik_file_routes:
+  - name: jellyfin
+    domain: jellyfin.example.invalid
+    scheme: http
+    port: 80
+  - name: gitea
+    domain: git.example.invalid
+    scheme: http
+    port: 80
+```
+
+When the play runs against the edge VM, Traefik renders
+`dynamic/http-services.yml` from `nbops_traefik_file_routes` declared across the
+inventory group. Each route targets `ansible_host` for that inventory host by
+default. Set `target_host` for a different VM address, or set `url` to provide
+the complete upstream URL.
+
+For future mTLS between edge Traefik and internal Traefik, routes can reference a
+Traefik `serversTransport`:
+
+```yaml
+nbops_traefik_file_routes:
+  - name: jellyfin
+    domain: jellyfin.example.invalid
+    scheme: https
+    port: 443
+    servers_transport: internal-mtls
+
+traefik_dynamic_servers_transports:
+  - name: internal-mtls
+    server_name: apps-01.example.internal
+    root_cas:
+      - /etc/pki/internal/certs/ca.crt
+    certificates:
+      - cert_file: /etc/pki/internal/certs/edge.crt
+        key_file: /etc/pki/internal/private/edge.key
+```
+
 ## Routing Modes
 
 Application roles support:
 
 - `host`: publish application ports directly and open those ports in UFW.
 - `traefik`: do not publish HTTP ports; attach to Traefik and render labels.
+- `traefik_file`: publish a service port without labels. This is available for
+  exceptional direct edge-to-app routes, but the preferred multi-VM topology is
+  edge Traefik -> internal Traefik -> application.
 
 Gitea is special: HTTP can be routed through Traefik while SSH remains published
 with `gitea_publish_ssh: true`.
-