KV-store providers

Four key-value-store backends share a common implementation under pkg/provider/kv/. Each one watches a path prefix and assembles dynamic.Configuration from the keys.

Common code

pkg/provider/kv/kv.go is the shared core. It defines:

• The shape of the keys: traefik/http/routers/<name>/rule, traefik/http/services/<name>/loadBalancer/servers/0/url, etc.
• A single decoder that turns key-value pairs into a dynamic.Configuration using struct-tag reflection.
• A storewrapper.go that adapts the various store libraries to one interface (List, Watch).

pkg/provider/kv/kv_test.go covers the decoding logic for shapes that are easy to get wrong (slices, maps, optional pointers).

Backends

Backend	Package	Library
Consul	pkg/provider/kv/consul/	github.com/hashicorp/consul/api.
etcd	pkg/provider/kv/etcd/	go.etcd.io/etcd/client/v3.
Redis	pkg/provider/kv/redis/	github.com/redis/go-redis.
ZooKeeper	pkg/provider/kv/zk/	github.com/go-zookeeper/zk.

Each backend wraps its native client into the Store interface and registers itself with the shared decoder.

Configuration shape

providers:
  consul:
    rootKey: traefik
    endpoints: ['consul:8500']

  etcd:
    rootKey: traefik
    endpoints: ['etcd:2379']

  redis:
    rootKey: traefik
    endpoints: ['redis:6379']
    db: 0

  zooKeeper:
    rootKey: traefik
    endpoints: ['zk:2181']

The rootKey (default traefik) is the prefix under which the configuration tree lives. Only one root is allowed per provider — the trick for multi-tenant setups is to use multiple Traefik instances each pointing at a different prefix.

Key layout

traefik/http/routers/api/rule = Host(`api.example.com`)
traefik/http/routers/api/service = api
traefik/http/services/api/loadBalancer/servers/0/url = http://backend:8080
traefik/http/services/api/loadBalancer/servers/1/url = http://backend2:8080
traefik/http/middlewares/auth/basicAuth/users/0 = admin:$apr1$...

The decoder walks the keys, splits them on /, and uses struct-tag reflection to assemble the configuration. List indices are 0-based numeric segments. Maps use the literal map key as a path segment.

Watching for changes

Each backend implements a Watch method that streams changes. Consul and etcd both expose native watch APIs; ZooKeeper uses ephemeral watches re-registered after each event; Redis uses keyspace notifications (which must be enabled server-side via notify-keyspace-events Kg).

Redis specifics

Redis is the odd one — it's a flat key-value store, not a tree. The provider stores configuration as Redis hashes per object. The keyspace-notification setup needs to be enabled by the operator; without it, the provider falls back to polling.

TLS and authentication

Each backend supports TLS to the store via the standard tls block (certFile, keyFile, caFile, insecureSkipVerify). Username/password is configured per backend (token for Consul, basic auth for etcd, password for Redis).

Tests

• pkg/provider/kv/kv_test.go — decoder coverage with mocked stores (kv_mock_test.go).
• integration/consul_test.go, etcd_test.go, redis_test.go, redis_sentinel_test.go, zk_test.go — end-to-end against real backends.

When to use a KV provider

KV providers are useful when:

• You already run a KV cluster and want one source of truth for both application config and reverse-proxy routes.
• You need a programmatic API for adding/removing routes (just write a key).
• You want the same configuration to be readable by other tools.

For most container-orchestrated setups, the Docker or Kubernetes providers are better fits — KV providers shine in custom deployments without a native discovery mechanism.

For pulling configuration over HTTP without a KV store, see HTTP and REST.