Agent API

The Traefik Hub API Gateway exposes a good deal of information through an API handler, such as the configuration of all routers, services, middlewares, etc.

---

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.

For example, 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 service named api@internal is created and can then be referenced in a router.

To enable the API handler, update the settings if your Traefik Hub installation.

First, save the default configuration. The following command will save it to a file with the name values.yaml in your working directory.

CLI

helm show values traefik/traefik-hub > values.yaml

Second, adjust the file.

values.yaml

additionalArguments:
  - --api=true

Install the Agent with Your Custom Settings

Once you have the configuration adjusted to your needs, use Helm to deploy the Traefik Hub agent with the new values:

CLI

helm upgrade --install --namespace traefik-hub traefik-hub traefik/traefik-hub --values values.yaml

And then define a routing configuration on Traefik Hub itself:

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard
spec:
  routes:
  - match: Host(`dev.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
    kind: Rule
    services:
    - name: api@internal
      kind: TraefikService
    middlewares:
      - name: auth-oidc
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: auth-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret

warning

The router's rule must catch requests for the URI path /api. Using a "Host" rule is recommended, by catching all the incoming traffic on this host domain to the API. You can also use "path prefix" rule or any combination of rules.

Details

Host Rule

# Matches http://dev.example.com, http://dev.example.com/api
# or http://dev.example.com/hello
rule = "Host(`dev.example.com`)"

Path Prefix Rule

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

Combination of Rules

# Matches http://dev.example.com/api or http://dev.example.com/dashboard
# but does not match http://dev.example.com/hello
rule = "Host(`dev.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.

First, save the default configuration. The following command will save it to a file with the name values.yaml in your working directory.

CLI

helm show values traefik/traefik-hub > values.yaml

Second, adjust the file.

values.yaml

additionalArguments:
  - --api.insecure=true

Install the Agent with Your Custom Settings

Once you have the configuration adjusted to your needs, use Helm to deploy the Traefik Hub agent with the new values:

CLI

helm upgrade --install --namespace traefik-hub traefik-hub traefik/traefik-hub --values values.yaml

dashboard

Field	Description	Default	Required
dashboard	Enable the dashboard.	True	No

First, save the default configuration. The following command will save it to a file with the name values.yaml in your working directory.

CLI

helm show values traefik/traefik-hub > values.yaml

Second, adjust the file.

values.yaml

additionalArguments:
  - --api.dashboard=true

Install the Agent with Your Custom Settings

Once you have the configuration adjusted to your needs, use Helm to deploy the Traefik Hub agent with the new values:

CLI

helm upgrade --install --namespace traefik-hub traefik-hub traefik/traefik-hub --values values.yaml

warning

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

Endpoints

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

Path	Description
/api/http/routers	Lists all the HTTP routers information.
/api/http/routers/{name}	Returns the information of the HTTP router specified by name.
/api/http/services	Lists all the HTTP services information.
/api/http/services/{name}	Returns the information of the HTTP service specified by name.
/api/http/middlewares	Lists all the HTTP middlewares information.
/api/http/middlewares/{name}	Returns the information of the HTTP middleware specified by name.
/api/tcp/routers	Lists all the TCP routers information.
/api/tcp/routers/{name}	Returns the information of the TCP router specified by name.
/api/tcp/services	Lists all the TCP services information.
/api/tcp/services/{name}	Returns the information of the TCP service specified by name.
/api/tcp/middlewares	Lists all the TCP middlewares information.
/api/tcp/middlewares/{name}	Returns the information of the TCP middleware specified by name.
/api/udp/routers	Lists all the UDP routers information.
/api/udp/routers/{name}	Returns the information of the UDP router specified by name.
/api/udp/services	Lists all the UDP services information.
/api/udp/services/{name}	Returns the information of the UDP service specified by name.
/api/entrypoints	Lists all the entry points information.
/api/entrypoints/{name}	Returns the information of the entry point specified by name.
/api/overview	Returns statistic information about HHTP, TCP and about enabled features and providers.
/api/rawdata	Returns information about dynamic configurations, errors, status and dependency relations.
/api/version	Returns information about Traefik version.
/debug/vars	See the expvar Go documentation.
/debug/pprof/	See the pprof Index Go documentation.
/debug/pprof/cmdline	See the pprof Cmdline Go documentation.
/debug/pprof/profile	See the pprof Profile Go documentation.
/debug/pprof/symbol	See the pprof Symbol Go documentation.
/debug/pprof/trace	See the pprof Trace Go documentation.