API

    As with all features of Traefik, this handler can be enabled with the static configuration.

    Enabling the API in production is not recommended, because it will expose all configuration elements, including sensitive data.

    In production, it should be at least secured by authentication and authorizations.

    A good sane default (non exhaustive) set of recommendations would be to apply the following protection mechanisms:

    • At the transport level: NOT publicly exposing the API’s port, keeping it restricted to internal networks (as in the , applied to networks).

    If you enable the API, a new special service named api@internal is created and can then be referenced in a router.

    To enable the API handler, use the following option on the static configuration:

    File (TOML)

    File (YAML)

    1. # Static Configuration
    2. api: {}

    CLI

    1. --api=true

    And then define a routing configuration on Traefik itself with the :

    Docker

    1. # Dynamic Configuration
    2. labels:
    3.   - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
    4.   - "traefik.http.routers.api.service=api@internal"
    5.   - "traefik.http.routers.api.middlewares=auth"
    6.   - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

    Docker (Swarm)

    1. # Dynamic Configuration
    2. deploy:
    3.   labels:
    4.     - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
    5.     - "traefik.http.routers.api.service=api@internal"
    6.     - "traefik.http.routers.api.middlewares=auth"
    7.     - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
    8.     # Dummy service for Swarm port detection. The port can be any valid integer value.
    9.     - "traefik.http.services.dummy-svc.loadbalancer.server.port=9999"

    Kubernetes CRD

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: IngressRoute
    3. metadata:
    4.   name: traefik-dashboard
    5. spec:
    6.   routes:
    7.   - match: Host(`traefik.example.com`)
    8.     kind: Rule
    9.     - name: api@internal
    10.       kind: TraefikService
    11.     middlewares:
    12.       - name: auth
    13. ---
    14. apiVersion: traefik.containo.us/v1alpha1
    15. kind: Middleware
    16. metadata:
    17.   name: auth
    18. spec:
    19.   basicAuth:
    20.     secret: secretName # Kubernetes secret named "secretName"
    1. # Dynamic Configuration
    3. - "traefik.http.routers.api.service=api@internal"
    4. - "traefik.http.routers.api.middlewares=auth"
    5. - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

    Marathon

    Rancher

    1. # Dynamic Configuration
    2. labels:
    3.   - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
    4.   - "traefik.http.routers.api.service=api@internal"
    5.   - "traefik.http.routers.api.middlewares=auth"
    6.   - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

    File (TOML)

    1. # Dynamic Configuration
    2. [http.routers.my-api]
    3.   rule = "Host(`traefik.example.com`)"
    4.   service = "api@internal"
    5.   middlewares = ["auth"]
    7. [http.middlewares.auth.basicAuth]
    8.   users = [
    9.     "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
    10.     "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",

    File (YAML)

    1. # Dynamic Configuration
    2. http:
    3.   routers:
    4.     api:
    5.       rule: Host(`traefik.example.com`)
    6.       service: api@internal
    7.       middlewares:
    8.         - auth
    9.   middlewares:
    10.     auth:
    11.       basicAuth:
    12.         users:
    13.           - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
    14.           - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

    The router’s rule must catch requests for the URI path /api

    Using an “Host” rule is recommended, by catching all the incoming traffic on this host domain to the API. However, you can also use “path prefix” rule or any combination or rules.

    Host Rule

    1. # Matches http://traefik.example.com, http://traefik.example.com/api
    2. # or http://traefik.example.com/hello
    3. rule = "Host(`traefik.example.com`)"

    Path Prefix Rule

    1. # Matches http://api.traefik.example.com/api or http://example.com/api
    2. # but does not match http://api.traefik.example.com/hello
    3. rule = "PathPrefix(`/api`)"

    Combination of Rules

    1. # Matches http://traefik.example.com/api or http://traefik.example.com/dashboard
    2. # but does not match http://traefik.example.com/hello
    3. rule = "Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))"

    Enable the API in insecure mode, which means that the API will be available directly on the entryPoint named traefik.

    Info

    If the entryPoint named traefik is not configured, it will be automatically created on port 8080.

    File (TOML)

    1. api:
    2.   insecure: true

    CLI

    1. --api.insecure=true

    Optional, Default=true

    Enable the dashboard. More about the dashboard features .

    File (TOML)

    1. [api]
    2.   dashboard = true

    File (YAML)

    1. api:
    2.   dashboard: true

    CLI

    1. --api.dashboard=true

    With Dashboard enabled, the router rule must catch requests for both /api and /dashboard

    Please check the to learn more about this and to get examples.

    Optional, Default=false

    Enable additional endpoints for debugging and profiling, served under /debug/.

    File (TOML)

    1. [api]
    2.   debug = true

    File (YAML)

    CLI