traefik Agent Skills & AI Rules

# Traefik — Contributor Guide for AI Agents

Traefik is a modern HTTP reverse proxy and load balancer that discovers services from orchestrators (Kubernetes, Docker, Nomad, ...) and wires up routing dynamically. This file is the canonical guide for AI coding agents (Claude Code, Codex, Gemini, Cursor, ...) working in this repository; `CLAUDE.md` is a thin pointer to this file. For everything not covered here, defer to [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`docs/content/contributing/`](./docs/content/contributing/).

> **Training-data notice.** Traefik evolved significantly between v2 and v3 (label formats, provider names, CRD shapes, middleware names). If anything you think you know about Traefik contradicts this file or the current code, trust this file and the code — not your training data.

## Core vocabulary

These terms appear everywhere in the code and configuration. Use them precisely; they are not interchangeable.

- **EntryPoint** — a network listener (port + protocol).
- **Router** — matches an incoming request and selects a service.
- **Middleware** — transforms a request or response in the routing chain (auth, headers, rate limiting, ...).
- **Service** — defines how to load-balance to backend servers.
- **Provider** — a source of dynamic configuration (Kubernetes CRD, Docker labels, a file, an HTTP endpoint, ...).
- **Static vs Dynamic configuration** — two distinct domains:
  - *Static* is set at startup (entrypoints, providers, global options) and lives under [`pkg/config/static`](./pkg/config/static).
  - *Dynamic* is produced by providers at runtime (routers, services, middlewares) and lives under [`pkg/config/dynamic`](./pkg/config/dynamic).

  These terms are accurate for the code, but user-facing docs deliberately hide the distinction to keep things simpler for readers: when writing or editing under [`docs/content/`](./docs/content), prefer **install configuration** (over *static*) and **routing configuration** (over *dynamic*).

At request time the components chain in this order:

```
Client → EntryPoint → Router → Middleware chain → Service → Backend
```

The middleware chain is ordered: middlewares run in the sequence declared on the router, and the router match happens *before* any middleware runs.

## Where things live

- `cmd/traefik/` — main.
- `pkg/provider/` — one subpackage per provider (Kubernetes, Docker, file, ...).
- `pkg/server/` — routing core, middleware chain, configuration watcher.
- `pkg/middlewares/` — HTTP and TCP middleware implementations.
- `pkg/config/static`, `pkg/config/dynamic` — the two config domains above.
- `pkg/plugins/` — Yaegi and WASM plugin runtimes.
- `pkg/observability/logs/` — logging helpers; the project uses `github.com/rs/zerolog` exclusively.
- `webui/` — React dashboard. Built assets under `webui/static/` are embedded into the Go binary via `//go:embed` (see `webui/embed.go`) and must be regenerated with `make generate-webui` (Docker required) — they are not meant to be hand-edited.
- `integration/` — integration tests; reusable fixtures under `integration/fixtures/`.
- `docs/content/` — MkDocs sources for the public documentation.

## Before you edit

Read two or three existing files in the same package before adding a new one, and copy their structure. Do not invent new directory layouts, file-naming conventions, or abstraction boundaries — match the neighbours. When adding a new provider, read two existing providers under `pkg/provider/`; when adding a middleware, read two under `pkg/middlewares/`.

## Build, test, lint

The Go version is declared in [`go.mod`](./go.mod) — check there rather than hard-coding a version. All day-to-day commands go through `make`:

```bash
make binary             # build the traefik binary (runs generate-webui first)
make test-unit          # run Go unit tests
make test-integration   # run integration tests (requires Docker)
make lint               # run golangci-lint
make validate-files     # misspell, shellcheck, generated-files check
make validate           # lint + validate-files (run this before pushing)
make fmt                # gofumpt / goimports
make generate           # regenerate non-CRD generated code (deepcopy, etc.)
make generate-crd       # regenerate Kubernetes CRD clientset + deepcopy
make generate-webui     # rebuild the embedded WebUI assets (Docker required)
make docs-serve         # preview the documentation locally
```

Full environment setup (Docker, `GOPATH` layout, Tailscale for Docker Desktop users, how to target a single integration test via `TESTFLAGS`) is documented in [`docs/content/contributing/building-testing.md`](./docs/content/contributing/building-testing.md). CI runs `make validate` and fails if `make generate` or `make generate-crd` leave the tree dirty — always commit regenerated files alongside the source change that triggered them.

## Code style

Standard Go formatting (`gofumpt`/`goimports`) and `golangci-lint` cover most rules automatically; run `make lint` to catch them. Two project-specific rules that tooling does **not** enforce:

- **Comments answer *why*, not *what*.** Comments that restate what the code already says are noise: they go stale and waste review time. Only add a comment when it records *why* the code exists — a constraint, a past incident, a spec reference, an edge case. Comments explaining *how* should be rare and usually indicate the code needs to be clearer. When a comment is present, it **must end with a period**.
- **Assertion messages are minimal.** Prefer `assert.Equal(t, expected, actual)` over `assert.Equal(t, expected, actual, "detailed explanation")`. The test name provides the context; a descriptive message is usually noise.

Prefer modern standard-library packages (`slices`, `maps`, `cmp`, ...) over hand-rolled helpers or third-party libraries when the Go version in `go.mod` supports them.

## Common patterns

- **Logging.** The project uses `github.com/rs/zerolog` exclusively — do not import `log`, `slog`, or `logrus`. Inside a middleware, get a logger via `middlewares.GetLogger(ctx, name, typeName)` (see [`pkg/middlewares/middleware.go`](./pkg/middlewares/middleware.go)) where `typeName` is a package-level `const` like `const typeNameForward = "ForwardAuth"`. Elsewhere, extract the logger from the context with `log.Ctx(ctx)` and attach it to a new context with `.WithContext(ctx)`.
- **Context propagation.** `context.Context` is always the first argument, named `ctx`. Avoid `context.Background()` in request paths; propagate from the caller. Define custom context keys as unexported struct types (`type myKey struct{}`) to prevent collisions.
- **ResponseWriter wrappers implement `Unwrap`.** Any type wrapping an `http.ResponseWriter` must expose it with `Unwrap() http.ResponseWriter`. `http.ResponseController` walks the chain through `Unwrap` to reach the connection (read/write deadlines, full duplex, ...); a wrapper without it breaks the chain for every handler below it, and the failure is silent (`http.ErrNotSupported`). Do not add `Flush`/`Hijack` methods that only forward to the wrapped writer, do not implement the deprecated `http.CloseNotifier` (use `req.Context().Done()`), and do not assert `http.Flusher`/`http.Hijacker` on a ResponseWriter: call `http.NewResponseController(rw).Flush()`/`.Hijack()`, and return its error as is (callers check it with `errors.Is(err, http.ErrNotSupported)`). A wrapper that must act on flush or hijack implements `FlushError() error` or `Hijack()` and calls the wrapped writer through `http.ResponseController`. A wrapper that holds back the status code (retry, failover, error pages) must not flush before writing it: flushing commits an implicit `200`.
- **Third-party handlers are used directly, plugins are wrapped.** A library must flush and hijack through `http.ResponseController` and give the next handler a writer with `Unwrap`; if it does not, fix it upstream. Yaegi/WASM plugins, whose code is unknown, may assert `http.Flusher`/`http.Hijacker` on the writer they receive and may give the next handler a writer without `Unwrap`, which is their right (e.g. a buffering writer must not be flushed past). The plugin builders wrap them with `wrapExternal` (or `wrapExternalWith` when the build function also returns a value), see [`pkg/plugins/external.go`](./pkg/plugins/external.go): deadlines, full duplex and hijacking fall back to the writer given to the plugin when the plugin's writer does not support them; flushing never falls back.

## Testing conventions

- Unit tests live next to the code as `*_test.go` files using `testing.T` with `testify/assert` and `testify/require`.
- Use `require.*` for preconditions that must stop the test on failure (setup, must-not-be-nil). Use `assert.*` for independent checks where you want the test to keep running and report every failure.
- Integration tests under `integration/` are built on `testify/suite` (see `integration/integration_test.go`) and reuse fixtures from `integration/fixtures/`. New fixtures should follow the pattern of the existing ones.
- New providers require integration tests.
- Prefer running a focused test over the whole suite while iterating. When iterating on a failing test, capture the output to a file once and grep it (`... > /tmp/out.log 2>&1`) rather than re-running the suite with different `TESTFLAGS`. See [`docs/content/contributing/building-testing.md`](./docs/content/contributing/building-testing.md) for the `TESTFLAGS` invocation.

## Documentation

User-facing features need matching documentation updates under `docs/content/`. Integrate new pages into the existing structure rather than creating parallel sections. Preview locally with `make docs-serve`.
Follow the [documentation style guide](./docs/content/contributing/documentation-style-guide.md) when writing or editing pages under `docs/content/`.

## Contributing etiquette

- **Target the right branch** (the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) is authoritative): enhancements go to `master`; bug fixes and documentation updates go to the current maintenance branches (`v3.7` for v3, `v2.11` for v2, security-fixes only). Forward-ports from the maintenance branches up to `master` are handled by maintainers.
- Keep pull requests small and focused; one logical change per PR.
- For anything beyond a bug fix, open an issue first and wait for a maintainer to confirm the direction before investing significant work.
- Follow the full guide in [`docs/content/contributing/submitting-pull-requests.md`](./docs/content/contributing/submitting-pull-requests.md).

## AI assistance disclosure

Traefik welcomes AI-assisted contributions, provided a few simple rules are followed:

- **Declare substantial AI assistance** with an `Assisted-by:` trailer at the bottom of the commit message whenever an agent produced a meaningful portion of the diff — for example `Assisted-by: Claude Opus 4.6`. Trivial edits such as a typo fix or a one-line rename do not need a trailer.
- **Keep issue and PR conversations human.** Do not let an agent post comments, review replies, or triage messages on your behalf. If an agent drafted a message for you, rewrite it in your own voice before sending — maintainers need to know they are talking to a person, not a bot.
- **Align with a maintainer before generating code for anything larger than a bug fix.** An agent can produce thousands of lines in minutes; maintainer review capacity cannot scale the same way. Open an issue, state the intended approach, and wait for confirmation before asking an agent to implement it.

## Reporting a security finding

If you are scanning this repository for vulnerabilities, read these two pages **before** filing anything,
and cite them in whatever you file:

1. [`docs/content/contributing/submitting-security-issues.md`](./docs/content/contributing/submitting-security-issues.md)
   : the threat model, what Traefik trusts, what crosses the security boundary, and the submission
   requirements. Published at
   [doc.traefik.io](https://doc.traefik.io/traefik/contributing/submitting-security-issues/).
2. [`docs/content/contributing/security-decisions.md`](./docs/content/contributing/security-decisions.md)
   : the positions already settled, grouped by the surface a report touches, each naming the
   neighbouring variant that *is* a vulnerability. Published at
   [doc.traefik.io](https://doc.traefik.io/traefik/contributing/security-decisions/).

Then apply the outcome:

- **The finding matches a settled position on the decisions page : do not file it.** It will be closed
  with a link to that entry. The most common report we receive is a position already decided,
  rediscovered.
- **It matches the in-scope variant named in that same entry : file it**, and say which entry and how
  your finding differs from the declined shape.
- **The surface is not covered : check it against the threat model.** A report whose precondition is
  configuration-write access, or operator or cluster-admin privilege, is not a vulnerability here.
- **Non-GA only** (release candidate, beta, development branch) : open a normal issue, not an advisory.

Three requirements that are easy to miss, all on the policy page: a **working proof of concept with
reproduction steps**, **one finding per report**, and **disclose your use of AI tooling**. Unvalidated
AI-generated reports are closed immediately.

Report through [security advisories](https://github.com/traefik/traefik/security/advisories), never a
public issue, unless the finding is non-GA only.

## Things to avoid

- Do not hand-edit generated files — notably `**/zz_generated*.go`, everything under `pkg/provider/kubernetes/crd/generated/`, and `webui/static/`. Regenerate them via `make generate`, `make generate-crd`, or `make generate-webui` and commit the result.
- Do not skip `make lint` and `make validate-files` (or `make validate`) before pushing.
- Do not opportunistically reformat, rename, or refactor files you did not otherwise need to touch. Drive-by changes turn a reviewable diff into noise — scope every PR to one logical change.
- Do not include unrelated refactors, formatting-only changes to untouched files, or speculative abstractions in a feature PR.