From dce9278193957d26ddd7e645042127b9f37fbef2 Mon Sep 17 00:00:00 2001
From: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>
Date: Thu, 26 Sep 2019 15:16:05 +0200
Subject: [PATCH] Add the router priority documentation

---
 docs/content/routing/providers/docker.md   |  3 +-
 docs/content/routing/providers/marathon.md |  3 +-
 docs/content/routing/providers/rancher.md  |  3 +-
 docs/content/routing/routers/index.md      | 79 ++++++++++++++++++++++
 4 files changed, 85 insertions(+), 3 deletions(-)

diff --git a/docs/content/routing/providers/docker.md b/docs/content/routing/providers/docker.md
index 1538b02cc..5ceccfcf1 100644
--- a/docs/content/routing/providers/docker.md
+++ b/docs/content/routing/providers/docker.md
@@ -202,7 +202,8 @@ For example, to change the rule, you could add the label ```traefik.http.routers
     ```
 
 ??? info "`traefik.http.routers.<router_name>.priority`"
-    <!-- TODO doc priority in routers page -->
+    
+    See [options](../routers/index.md#priority) for more information.
     
     ```yaml
     - "traefik.http.routers.myrouter.priority=42"
diff --git a/docs/content/routing/providers/marathon.md b/docs/content/routing/providers/marathon.md
index 6c77076bb..2160932de 100644
--- a/docs/content/routing/providers/marathon.md
+++ b/docs/content/routing/providers/marathon.md
@@ -125,7 +125,8 @@ For example, to change the routing rule, you could add the label ```"traefik.htt
     ```
 
 ??? info "`traefik.http.routers.<router_name>.priority`"
-    <!-- TODO doc priority in routers page -->
+    
+    See [options](../routers/index.md#priority) for more information.
     
     ```json
     "traefik.http.routers.myrouter.priority": "42"
diff --git a/docs/content/routing/providers/rancher.md b/docs/content/routing/providers/rancher.md
index a37f80d25..6406cf227 100644
--- a/docs/content/routing/providers/rancher.md
+++ b/docs/content/routing/providers/rancher.md
@@ -130,7 +130,8 @@ For example, to change the rule, you could add the label ```traefik.http.routers
     ```
 
 ??? info "`traefik.http.routers.<router_name>.priority`"
-    <!-- TODO doc priority in routers page -->
+    
+    See [options](../routers/index.md#priority) for more information.
     
     ```yaml
     - "traefik.http.routers.myrouter.priority=42"
diff --git a/docs/content/routing/routers/index.md b/docs/content/routing/routers/index.md
index 0a935f826..51d8421b0 100644
--- a/docs/content/routing/routers/index.md
+++ b/docs/content/routing/routers/index.md
@@ -253,6 +253,85 @@ The table below lists all the available matchers:
     For instance, `PathPrefix: /products` would match `/products` but also `/products/shoes` and `/products/shirts`.
     Since the path is forwarded as-is, your service is expected to listen on `/products`.
 
+### Priority
+
+To avoid path overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority.
+
+A value of `0` for the priority is ignored: `priority = 0` means that the default rules length sorting is used.
+
+??? info "How default priorities are computed"
+
+    ```toml tab="File (TOML)"
+    ## Dynamic configuration
+    [http.routers]
+      [http.routers.Router-1]
+        rule = "HostRegexp(`.*\.traefik\.com`)"
+        # ...
+      [http.routers.Router-2]
+        rule = "Host(`foobar.traefik.com`)"
+        # ...
+    ```
+    
+    ```yaml tab="File (YAML)"
+    ## Dynamic configuration
+    http:
+      routers:
+        Router-1:
+          rule: "HostRegexp(`.*\.traefik\.com`)"
+          # ...
+        Router-2:
+          rule: "Host(`foobar.traefik.com`)"
+          # ...
+    ```
+    
+    In this case, all requests with host `foobar.traefik.com` will be routed through `Router-1` instead of `Router-2`.
+    
+    | Name     | Rule                                 | Priority |
+    |----------|--------------------------------------|----------|
+    | Router-1 | ```HostRegexp(`.*\.traefik\.com`)``` | 30       |
+    | Router-2 | ```Host(`foobar.traefik.com`)```     | 26       |
+    
+    The previous table shows that `Router-1` has a higher priority than `Router-2`.
+    
+    To solve this issue, the priority must be setted.
+
+??? example "Set priorities -- using the [File Provider](../../providers/file.md)"
+    
+    ```toml tab="File (TOML)"
+    ## Dynamic configuration
+    [http.routers]
+      [http.routers.Router-1]
+        rule = "HostRegexp(`.*\.traefik\.com`)"
+        entryPoints = ["web"]
+        service = "service-1"
+        priority = 1
+      [http.routers.Router-2]
+        rule = "Host(`foobar.traefik.com`)"
+        entryPoints = ["web"]
+        priority = 2
+        service = "service-2"
+    ```
+    
+    ```yaml tab="File (YAML)"
+    ## Dynamic configuration
+    http:
+      routers:
+        Router-1:
+          rule: "HostRegexp(`.*\.traefik\.com`)"
+          entryPoints:
+          - "web"
+          service: service-1
+          priority: 1
+        Router-2:
+          rule: "Host(`foobar.traefik.com`)"
+          entryPoints:
+          - "web"
+          priority: 2
+          service: service-2
+    ```
+
+    In this configuration, the priority is configured to allow `Router-2` to handle requests with the `foobar.traefik.com` host.
+
 ### Middlewares
 
 You can attach a list of [middlewares](../../middlewares/overview.md) to each HTTP router.