API

Traefik exposes a number of information through an API handler, such as the configuration of all routers, services, middlewares, etc.

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

Security

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 principle of least privilege, applied to networks).

Configuration

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 (YAML)

  1. # Static Configuration
  2. api: {}

File (TOML)

  1. # Static Configuration
  2. [api]

CLI

  1. --api=true

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

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. services:
  10. - name: api@internal
  11. kind: TraefikService
  12. middlewares:
  13. - name: auth
  14. ---
  15. apiVersion: traefik.containo.us/v1alpha1
  16. kind: Middleware
  17. metadata:
  18. name: auth
  19. spec:
  20. basicAuth:
  21. secret: secretName # Kubernetes secret named "secretName"

Consul Catalog

  1. # Dynamic Configuration
  2. - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
  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

  1. "labels": {
  2. "traefik.http.routers.api.rule": "Host(`traefik.example.com`)",
  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"
  6. }

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 (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"

File (TOML)

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

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`))"

insecure

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 (YAML)

  1. api:
  2. insecure: true

File (TOML)

  1. [api]
  2. insecure = true

CLI

  1. --api.insecure=true

dashboard

Optional, Default=true

Enable the dashboard. More about the dashboard features here.

File (YAML)

  1. api:
  2. dashboard: true

File (TOML)

  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 Dashboard documentation to learn more about this and to get examples.

debug

Optional, Default=false

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

File (YAML)

  1. api:
  2. debug: true

File (TOML)

  1. [api]
  2. debug = true

CLI

  1. --api.debug=true

Endpoints

All the following endpoints must be accessed with a GET HTTP request.

PathDescription
/api/http/routersLists all the HTTP routers information.
/api/http/routers/{name}Returns the information of the HTTP router specified by name.
/api/http/servicesLists all the HTTP services information.
/api/http/services/{name}Returns the information of the HTTP service specified by name.
/api/http/middlewaresLists all the HTTP middlewares information.
/api/http/middlewares/{name}Returns the information of the HTTP middleware specified by name.
/api/tcp/routersLists all the TCP routers information.
/api/tcp/routers/{name}Returns the information of the TCP router specified by name.
/api/tcp/servicesLists all the TCP services information.
/api/tcp/services/{name}Returns the information of the TCP service specified by name.
/api/entrypointsLists all the entry points information.
/api/entrypoints/{name}Returns the information of the entry point specified by name.
/api/overviewReturns statistic information about http and tcp as well as enabled features and providers.
/api/versionReturns information about Traefik version.
/debug/varsSee the expvar Go documentation.
/debug/pprof/See the pprof Index Go documentation.
/debug/pprof/cmdlineSee the pprof Cmdline Go documentation.
/debug/pprof/profileSee the pprof Profile Go documentation.
/debug/pprof/symbolSee the pprof Symbol Go documentation.
/debug/pprof/traceSee the pprof Trace Go documentation.