Configurable API & Dashboard base path

Co-authored-by: Kevin Pollet <pollet.kevin@gmail.com>

docs/content/operations/dashboard.md

@@ -87,8 +87,44 @@ rule = "Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashb
 ??? example "Dashboard Dynamic Configuration Examples"
     --8<-- "content/operations/include-dashboard-examples.md"
 
+### Custom API Base Path
+
+As shown above, by default Traefik exposes its API and Dashboard under the `/` base path,
+which means that respectively the API is served under the `/api` path,
+and the dashboard under the `/dashboard` path.
+
+However, it is possible to configure this base path:
+
+```yaml tab="File (YAML)"
+api:
+  # Customizes the base path:
+  # - Serving API under `/traefik/api`
+  # - Serving Dashboard under `/traefik/dashboard`
+  basePath: /traefik
+```
+
+```toml tab="File (TOML)"
+[api]
+  # Customizes the base path:
+  # - Serving API under `/traefik/api`
+  # - Serving Dashboard under `/traefik/dashboard`
+  basePath = "/traefik"
+```
+
+```bash tab="CLI"
+# Customizes the base path:
+# - Serving API under `/traefik/api`
+# - Serving Dashboard under `/traefik/dashboard`
+--api.basePath=/traefik
+```
+
+??? example "Dashboard Under Custom Path Dynamic Configuration Examples"
+    --8<-- "content/operations/include-dashboard-custom-path-examples.md"
+
 ## Insecure Mode
 
+!!! warning "Please note that this mode is incompatible with the [custom API base path option](#custom-api-base-path)."
+
 When _insecure_ mode is enabled, one can access the dashboard on the `traefik` port (default: `8080`) of the Traefik instance,
 at the following URL: `http://<Traefik IP>:8080/dashboard/` (trailing slash is mandatory).
 

docs/content/operations/include-dashboard-custom-path-examples.md

@@ -0,0 +1,83 @@
+```yaml tab="Docker & Swarm"
+# Dynamic Configuration
+labels:
+  - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && PathPrefix(`/traefik`)"
+  - "traefik.http.routers.dashboard.service=api@internal"
+  - "traefik.http.routers.dashboard.middlewares=auth"
+  - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
+```
+
+```yaml tab="Docker (Swarm)"
+# Dynamic Configuration
+deploy:
+  labels:
+    - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && PathPrefix(`/traefik`)"
+    - "traefik.http.routers.dashboard.service=api@internal"
+    - "traefik.http.routers.dashboard.middlewares=auth"
+    - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
+    # Dummy service for Swarm port detection. The port can be any valid integer value.
+    - "traefik.http.services.dummy-svc.loadbalancer.server.port=9999"
+```
+
+```yaml tab="Kubernetes CRD"
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: traefik-dashboard
+spec:
+  routes:
+  - match: Host(`traefik.example.com`) && PathPrefix(`/traefik`)
+    kind: Rule
+    services:
+    - name: api@internal
+      kind: TraefikService
+    middlewares:
+      - name: auth
+---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: auth
+spec:
+  basicAuth:
+    secret: secretName # Kubernetes secret named "secretName"
+```
+
+```yaml tab="Consul Catalog"
+# Dynamic Configuration
+- "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && PathPrefix(`/traefik`)"
+- "traefik.http.routers.dashboard.service=api@internal"
+- "traefik.http.routers.dashboard.middlewares=auth"
+- "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
+```
+
+```yaml tab="File (YAML)"
+# Dynamic Configuration
+http:
+  routers:
+    dashboard:
+      rule: Host(`traefik.example.com`) && PathPrefix(`/traefik`)
+      service: api@internal
+      middlewares:
+        - auth
+  middlewares:
+    auth:
+      basicAuth:
+        users:
+          - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
+          - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
+```
+
+```toml tab="File (TOML)"
+# Dynamic Configuration
+[http.routers.my-api]
+  rule = "Host(`traefik.example.com`) && PathPrefix(`/traefik`)"
+  service = "api@internal"
+  middlewares = ["auth"]
+
+[http.middlewares.auth.basicAuth]
+  users = [
+    "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
+    "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
+  ]
+```

docs/content/reference/static-configuration/cli-ref.md

@@ -42,6 +42,9 @@ Access log format: json | common (Default: ```common```)
 `--api`:  
 Enable api/dashboard. (Default: ```false```)
 
+`--api.basepath`:  
+Defines the base path where the API and Dashboard will be exposed. (Default: ```/```)
+
 `--api.dashboard`:  
 Activate dashboard. (Default: ```true```)
 

docs/content/reference/static-configuration/env-ref.md

@@ -42,6 +42,9 @@ Access log format: json | common (Default: ```common```)
 `TRAEFIK_API`:  
 Enable api/dashboard. (Default: ```false```)
 
+`TRAEFIK_API_BASEPATH`:  
+Defines the base path where the API and Dashboard will be exposed. (Default: ```/```)
+
 `TRAEFIK_API_DASHBOARD`:  
 Activate dashboard. (Default: ```true```)
 

docs/content/reference/static-configuration/file.toml

@@ -294,6 +294,7 @@
       name1 = "foobar"
 
 [api]
+  basePath = "foobar"
   insecure = true
   dashboard = true
   debug = true

docs/content/reference/static-configuration/file.yaml

@@ -330,6 +330,7 @@ providers:
       name0: foobar
       name1: foobar
 api:
+  basePath: foobar
   insecure: true
   dashboard: true
   debug: true