certctl/docs/reference/connectors/traefik.md

Traefik Connector — Operator Deep-Dive

Last reviewed: 2026-05-05

Operator-grade documentation for the Traefik target connector. For the connector-development context (interface contract, registry, atomic deploy primitive shared across all targets), see the connector index.

Overview

The Traefik connector uses Traefik's file provider — it writes certificate and key files to a watched directory, and Traefik automatically picks up the changes without any explicit reload command. This is the simplest deployment model in the catalog: write the files, Traefik does the rest.

Implementation lives at internal/connector/target/traefik/.

When to use this connector

Use the Traefik connector when:

• Traefik fronts your services with the file provider configured (providers.file.directory in Traefik's static config).
• You want a no-reload deployment path — Traefik picks up file changes automatically.

Look elsewhere when:

• You're running Traefik with its built-in ACME client. Either point Traefik at certctl's ACME server (see migration/acme-from-traefik.md) or let certctl-issued certs flow through this file-provider connector — but don't run both.
• Traefik is not exposed (e.g. behind another reverse proxy that terminates TLS); the front-most TLS terminator is what wants the cert.

Configuration

{
  "cert_dir": "/etc/traefik/certs",
  "cert_file": "site.crt",
  "key_file": "site.key"
}

The cert_dir is the directory Traefik is configured to watch via its file provider. The connector writes cert_file and key_file into this directory with appropriate permissions (0644 for the cert, 0600 for the key). Traefik's file watcher detects the change and reloads the TLS configuration automatically.

Deploy contract

Every cert deploy follows the Bundle I deploy.Apply(ctx, plan) flow:

1. Idempotency check on cert + key bytes.
2. Pre-deploy backup of existing files.
3. Atomic write of cert + key to temp paths.
4. Atomic rename of temp paths to final cert / key paths.
5. No reload command — Traefik's file watcher handles it.
6. Post-deploy TLS verify when configured (dials the endpoint; pulls leaf cert SHA-256; compares).

The validate / reload / rollback semantics that NGINX and HAProxy depend on don't apply here — Traefik's file watcher is the "reload"; if Traefik fails to load the new file, that's a Traefik problem visible in Traefik's logs, and the previous cert remains served until Traefik retries.

Operator playbook

File watcher latency

Traefik's file watcher polls the directory; the cert may take a few seconds to be picked up after the atomic rename. Post-deploy verify with PostDeployVerifyAttempts: 5 and a small backoff covers this comfortably.

Multi-router deployments

Traefik routes traffic by hostname, and the file provider can expose multiple certs in the same directory. Configure one certctl target per cert (one cert_file + key_file pair per hostname); they all land in the same watched directory and Traefik picks them up.

Mixing file provider with ACME

If Traefik is also running its own ACME client, both can write to the same certificatesResolvers config but with different storage backends. Best practice: don't mix. Pick one source of truth — either Traefik's ACME or certctl-supplied files — and delete the other config block from traefik.yml.

Related docs

• Connector index — interface contract, registry, deploy primitive
• NGINX — explicit-reload deploy contract counterpart
• Migration: point Traefik at certctl's ACME — alternative pattern when Traefik should pull rather than have certctl push