traefik-helm-chart

# AGENTS.md

This file provides guidance to AI coding agents working with this repository.

## Commands

All commands run via Docker — no local tool installs required.

```bash
make test          # Run unit tests (helm-unittest)
make lint          # Static linting via chart-testing (ct)
make test-ns       # Check namespace handling
make docs          # Regenerate traefik/VALUES.md via helm-docs
make schema        # Regenerate values.schema.json (requires helm-schema plugin: helm plugin install https://github.com/losisin/helm-values-schema-json.git)
make changelog     # Update Changelogs
make test-changelog # Golden tests for the artifacthub.io/changes annotation
```

Run a single unit test file:
```bash
helm unittest -f 'tests/TESTNAME_test.yaml' traefik
# Or via Docker (same as make test but filtered):
# Edit hack/test.sh temporarily, or run docker command from Makefile with -f flag
```

## Architecture

The Helm chart lives entirely in `traefik/`. Key directories:

- `traefik/templates/` — rendered K8s manifests
- `traefik/templates/_podtemplate.tpl` — shared pod spec (Deployment + DaemonSet both use it)
- `traefik/templates/_service.tpl` — shared service spec
- `traefik/templates/_helpers.tpl` — common helper functions
- `traefik/templates/requirements.yaml` — builds Traefik CLI args, ports, env from values
- `traefik/crds/` — CRD files (traefik.io_*, hub.traefik.io_*, gateway-standard-install.yaml)
- `traefik/tests/` — helm-unittest test files (`*_test.yaml`) + snapshots + test values
- `traefik/values.yaml` — 1570-line canonical values file
- `traefik/values.schema.json` — auto-generated JSON schema, never edit manually

Traefik can run as a `Deployment` or `DaemonSet` — controlled by `deployment.kind`. The pod template is shared between both via `_podtemplate.tpl`.

**CRDs are intentionally not upgraded by Helm** (Helm limitation). CRDs in `traefik/crds/` are applied on first install only. Do not templatize CRDs.

## Values and Documentation

- Document values with helm-docs `# --` comments above each field
- Use `# @schema` inline annotations for schema constraints (enum, type, default)
- Separate primary keys in `values.yaml` with an empty commented line (`#`)
- `VALUES.md` and `values.schema.json` are both auto-generated — regenerate with `make docs` and `make schema`

Example pattern:
```yaml
log:
  # -- Set [logs format](https://doc.traefik.io/traefik/observability/logs/#format)
  format:  # @schema enum:["common", "json", null]; type:[string, null]; default: "common"
```

## Templating Conventions

- Always chomp whitespace in conditionals: `{{- if .Values.foo }}` / `{{- end }}`
- Values names don't need to mirror Traefik config field names — optimize for UX

## Testing

TDD is required: write a failing test first, then implement. Test files live in `traefik/tests/`. Snapshots in `traefik/tests/__snapshot__/` are auto-generated by `make test`.

## Commit Messages

Conventional commits with scope required. All commits appear in the changelog.

```
feat(deployment): support hostUsers field
fix(ingressroute): use spec.ingressClassName with Proxy v3.7+
chore(deps): update traefik image to v3.7.1
```

## Philosophy (Scope Boundaries)

Contributions must align with the chart's philosophy. Avoid introducing:
- Specific end-user use cases
- Third-party CRDs
- Dashboard exposition tuning
- Values that shortcut or expose static/dynamic Traefik configuration verbatim

More agent context in traefik/traefik-helm-chart

One other file this repository gives its agents.