Migrating from Traefik

Sōzune reads the same kind of container labels as Traefik, with a flatter shape. This page maps the Traefik labels you most likely use to their Sōzune equivalent.

The model in one example

Traefik splits a route into a router, a service and named middlewares, linked by name:

copy
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.api.rule=Host(`api.example.com`) && PathPrefix(`/v1`)"
  - "traefik.http.routers.api.entrypoints=websecure"
  - "traefik.http.routers.api.tls.certresolver=letsencrypt"
  - "traefik.http.routers.api.middlewares=api-strip,api-ratelimit"
  - "traefik.http.middlewares.api-strip.stripprefix.prefixes=/v1"
  - "traefik.http.middlewares.api-ratelimit.ratelimit.average=100"
  - "traefik.http.middlewares.api-ratelimit.ratelimit.burst=50"
  - "traefik.http.services.api.loadbalancer.server.port=8080"

Sōzune has one level: every setting of a route sits under sozune.http.<svc>., middlewares included.

copy
labels:
  - "sozune.enable=true"
  - "sozune.http.api.host=api.example.com"
  - "sozune.http.api.path=/v1"
  - "sozune.http.api.tls=true"
  - "sozune.http.api.acme.resolver=letsencrypt"
  - "sozune.http.api.httpsRedirect=true"
  - "sozune.http.api.stripPrefix=true"
  - "sozune.http.api.ratelimit.average=100"
  - "sozune.http.api.ratelimit.burst=50"
  - "sozune.http.api.port=8080"

No rule language, no middleware names to keep in sync, no entrypoint to pick for plain HTTP or HTTPS routes. The letsencrypt resolver has to be declared under acme.resolvers in Sōzune's config, like the Traefik certificate resolver in its static config.

Discovery

Router rules

A Traefik rule becomes one label per matcher. All the matchers of a route must match.

matchHeaders chooses between routes, as Header() does: two routers on the same host and path that differ only by a header translate one to one, and a request without the header goes to the other route. A route whose header conditions hold comes before every route without any, whatever their priority.

matchQuery chooses between routes too, as Query() does, for up to three conditions on a route without pathRegex, stripPrefix or addPrefix. matchClientIP filters a route, it does not choose between routes: Sōzune picks the route, then answers 404 when the client IP is not listed, without trying another route. Two Traefik routers on the same host and path that differ only by a client IP need distinct paths in Sōzune. See Header & query matching.

A rule that mixes || across different matcher types has no single-route equivalent: declare one service per alternative. Each of them needs a host, so an alternative on a path alone, on any host, cannot be expressed with labels.

TLS and certificates

Service

Containers that declare the same <svc> name with the same hosts and paths are merged as backends of one route, like replicas of a Traefik service. If their hosts or paths differ, the later container gets a route of its own instead.

Middlewares

In Sōzune, a middleware is a label on the route itself: there is no middlewares= list and no shared middleware definition.

Not available yet: chain, digestauth, buffering, redirectregex, replacepath, replacepathregex, mirroring and weighted services. A weighted split between two versions is written with a weight on the containers of one service instead: see Weighted load balancing.

TCP

Check the result

Once the labels are rewritten, sozune validate reads them without starting the proxy and reports every unknown or invalid label, with a suggestion for typos. On a running instance, the dashboard's Diagnostics page shows the same, and sozune route <url> tells you which route a request reaches and why.