# Traefik

- Canonical URL: https://docs.fairvisor.com/docs/gateway/traefik/
- Section: docs
- Last updated: n/a
> Integrating Fairvisor Edge with Traefik using the forwardAuth middleware.


Traefik's `forwardAuth` middleware delegates request authorization to an external service. Fairvisor Edge's `/v1/decision` endpoint is fully compatible.

## Kubernetes CRD

```yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: fairvisor-auth
  namespace: default
spec:
  forwardAuth:
    address: http://fairvisor-edge.default.svc.cluster.local:8080/v1/decision
    trustForwardHeader: true
    authResponseHeaders:
      - X-Fairvisor-Reason
      - Retry-After
      - RateLimit
      - RateLimit-Limit
      - RateLimit-Remaining
      - RateLimit-Reset
```

`authResponseHeaders` lists the headers from the Fairvisor response that Traefik should forward to the backend (on allow) or to the client (on reject). Include at minimum `Retry-After` and `X-Fairvisor-Reason`.
Policy/rule attribution is debug-session-only (`X-Fairvisor-Debug-*`).

## Attaching to an IngressRoute

```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-api
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: PathPrefix(`/api/`)
      kind: Rule
      services:
        - name: my-api-service
          port: 3000
      middlewares:
        - name: fairvisor-auth
```

## Docker Compose labels

```yaml
services:
  my-api:
    image: my-api:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-api.rule=PathPrefix(`/api/`)"
      - "traefik.http.routers.my-api.middlewares=fairvisor-auth@docker"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.address=http://fairvisor-edge:8080/v1/decision"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.trustforwardheader=true"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.authResponseHeaders=Retry-After,X-Fairvisor-Reason,RateLimit-Remaining"
```

## Static configuration (traefik.yml)

```yaml
http:
  middlewares:
    fairvisor-auth:
      forwardAuth:
        address: "http://fairvisor-edge:8080/v1/decision"
        trustForwardHeader: true
        authResponseHeaders:
          - X-Fairvisor-Reason
          - Retry-After
          - RateLimit-Limit
          - RateLimit-Remaining
          - RateLimit-Reset
```

## Headers forwarded to Fairvisor

Traefik forwards the original request headers to the `forwardAuth` endpoint, including `Authorization`. Fairvisor Edge extracts JWT claims, client IP, and other descriptor keys from these headers automatically.

`trustForwardHeader: true` instructs Traefik to trust the `X-Forwarded-For` header from upstream, so Fairvisor sees the correct client IP when Traefik sits behind another proxy.

## Timeout

The default `forwardAuth` timeout in Traefik is **30 seconds**. Reduce it to a few hundred milliseconds to avoid stalling requests if Fairvisor Edge is slow:

```yaml
forwardAuth:
  address: "http://fairvisor-edge:8080/v1/decision"
  authRequestHeaders:
    - Authorization
  # Traefik does not expose a direct timeout field here;
  # configure the Fairvisor Edge service dial/read timeout
  # via the Traefik service definition.
```

## Failure mode

Traefik `forwardAuth` fails-closed by default: if the auth service is unreachable, the request is rejected with `500`. To implement fail-open, run a small nginx sidecar in front of Fairvisor Edge that returns `200` on upstream errors, or handle it at the service mesh level.