Learn Traefik - Path & Request Middlewares

#Introduction

Public URLs do not always have to match an application's internal paths exactly. Sometimes the backend expects requests at /api/v1 while users arrive at /api. Sometimes an application is deployed on a sub-path, or an HTTP to HTTPS redirect must be done once for all services. Episode 11 covers the middlewares that solve all these problems: path and request middlewares.

The six middlewares we dissect — AddPrefix, StripPrefix, ReplacePath, ReplacePathRegex, RedirectScheme, RedirectRegex — are everyday tools for adjusting request paths. After this episode, you can design configurations that unify public URLs with internal architecture without changing application code.

#AddPrefix and StripPrefix

#Adding a Prefix

AddPrefix attaches a prefix in front of the request path before forwarding to the backend. Useful when the backend expects a path with a certain prefix even though users arrive without it. The addPrefix middleware is defined like this:

http:
  middlewares:
    add-v1:
      addPrefix:
        prefix: "/v1"

A router using this middleware forwards a /users request as /v1/users on the backend side. This resembles a setup where a single backend hosts several API versions.

#Removing a Prefix

StripPrefix does the opposite: removes one or more prefixes from the path. The classic pattern is a reverse proxy to an application deployed on a sub-path:

http:
  middlewares:
    strip-docs:
      stripPrefix:
        prefixes:
          - /docs
        forceSlash: false

If a user accesses /docs/installation, the backend only receives /installation. The prefixes list allows several prefixes at once. The forceSlash: true option ensures the result still starts with a slash even if it is empty. An example applied via Docker labels:

services:
  docs:
    image: nginx:alpine
    labels:
      - traefik.enable=true
      - traefik.http.routers.docs.rule=Host(`docs.localhost`) && PathPrefix(`/docs`)
      - traefik.http.routers.docs.middlewares=strip-docs
      - traefik.http.middlewares.strip-docs.stripprefix.prefixes=/docs
      - traefik.http.routers.docs.service=docs-svc
      - traefik.http.services.docs-svc.loadbalancer.server.port=80

#ReplacePath and ReplacePathRegex

#Full Path Replacement

ReplacePath replaces the entire path with a single fixed value. Example: an old backend only recognizes the path /callback for everything:

http:
  middlewares:
    fix-path:
      replacePath:
        path: "/callback"

Every request with any path is forwarded as /callback. This middleware is versatile but crude — use it only when truly necessary.

#Regex-Based Replacement

ReplacePathRegex is far more precise: it replaces part of a path based on a regex pattern and template:

http:
  middlewares:
    versioned:
      replacePathRegex:
        regex: "^/api/(v[0-9]+)/users/(.*)"
        replacement: "/${1}/internal/${2}"

A /api/v2/users/42 request becomes /v2/internal/42. Capture groups like ${1} and ${2} refer to the parts captured by the regex pattern. This middleware is the right choice for gradual URL migrations where two path forms must coexist.

#RedirectScheme

#Forcing HTTP to HTTPS

RedirectScheme is the easiest way to force all traffic to HTTPS. It returns a 301 redirect to the exact same URL with the new scheme:

http:
  middlewares:
    https-redirect:
      redirectScheme:
        scheme: https
        permanent: true
        port: "443"

Attach this middleware to a router on the web (HTTP) entrypoint, while the real router is on the websecure (HTTPS) entrypoint:

http:
  routers:
    app-redirect:
      rule: "Host(`app.example.com`)"
      entrypoints:
        - web
      middlewares:
        - https-redirect
      service: dummy

With this pattern, a browser visiting http://app.example.com is immediately redirected to https://app.example.com before the request reaches the application. This prevents the application from ever seeing plaintext traffic.

#RedirectRegex

#Pattern-Based Redirects

RedirectRegex moves users from one URL pattern to another with a configurable status code:

http:
  middlewares:
    old-domain:
      redirectRegex:
        regex: "^https://old.example.com/(.*)"
        replacement: "https://new.example.com/${1}"
        permanent: true

A https://old.example.com/blog/hello request is permanently redirected to https://new.example.com/blog/hello. The permanent: true option uses status 301; a value of false uses 302 for temporary redirects. This pattern is very common during domain migrations or public path restructuring.

#Closing

Key takeaways:

• AddPrefix adds a prefix; StripPrefix removes prefixes from the path.
• ReplacePath replaces the entire path; ReplacePathRegex replaces part of it with regex.
• RedirectScheme forces HTTP to HTTPS with 301.
• RedirectRegex redirects URLs based on patterns with permanent or temporary status.
• Combined path middlewares change public URLs without touching the application.
• Always test middleware combinations with curl -I.

In episode 12 next we will cover rate limiting & circuit breaker — the RateLimit middleware with average and burst, InFlightReq for limiting concurrent requests, the CircuitBreaker based on error ratio expressions, and the Retry middleware for automatic retries. This is where you start protecting backends from traffic spikes.