Rotates the selected Traefik service certificate with TLS verification, backup and rollback.
What happens
- The service agent on the server fetches the task from the appliance over outbound HTTPS, port 443.
- Discovery finds the running v2/v3 service, YAML/TOML/CLI configuration, labels and file provider. Verified TLS and fingerprints map each router/SNI target to the certificate actually served.
- The agent checks the certificate, key, chain and targets, saves a protected backup and changes only the selected binding through tls.certificates certFile/keyFile. default@file explicitly selects the shared defaultCertificate.
- File watch normally reloads without restart. Verify checks the new served fingerprint and other verified targets. Activation failure triggers automatic rollback and verification of the previous certificate. If it fails: Rollback is verified against the previous fingerprint. Later edits are retained; a conflict requires the concrete file state to be resolved.
Technical details
- Connection
- The package runs through the service agent on the server. The agent connects over outbound HTTPS to the appliance, port 443 by default. You open no port into the server.
- Service ports
- 443
- You need
- The service agent installed on the server. Run on Linux through the service agent or SSH with access to the Traefik process, configuration and certificate files. Requires Bash, Python 3.11 or later with PyYAML, cryptography and tomli-w, and OpenSSL. Docker requires Docker CLI access and the actual host mounts; Compose label takeover requires the Compose plugin. The account must write the selected files and control the selected service when restart is permitted. Current TLS must verify with system trust or TLS_CA_BUNDLE.
- Platform
- Traefik v2/v3 on Linux and Docker
- Actions
- Discovery, Installation, Verification, Rollback
- Packages
-
traefik1.0.0 - Note
-
- Traefik 1.0.0 is a signing candidate. The package is not yet published in the agent catalogue.
- Select TRAEFIK_CONTAINER or TRAEFIK_UNIT/TRAEFIK_PID and TRAEFIK_ROUTER with @file/@docker. LOCAL_TLS_HOST, LOCAL_TLS_PORT and LOCAL_TLS_SNI can refine the target. TLS_CA_BUNDLE uses a local CA file; otherwise system trust applies. CA, SAN and validity are always verified.
- providers.file filename/directory and actual container/host paths determine activation. A single-file bind mount is written on the same inode; a stale mount after host rename needs correction. With watch=false, v3 uses SIGHUP; v2 requires ALLOW_RESTART=true and a selected service restart.
- Selecting the Traefik target transfers its ACME management. The required restart needs ALLOW_RESTART=true. The agent detaches the selected router resolver in file configuration or verified Compose labels and stops Traefik before retiring only selected cache records. certificatesResolvers, acme.json, accounts and other certificates remain.
- TLS certificates are selected before HTTP routing. Overlapping SANs/wildcards and the default store can affect multiple routers; the agent checks that scope plus tls.domains and inherited entrypoint domains before changing it. Ambiguous ownership or mounts stop without writes and produce a shareable log without keys or passwords.
- Backup and journal are protected outside watched configuration. Rollback restores only the agent’s own unchanged transaction and preserves later administrator edits. Retain BACKUP_PATH for separate rollback. Discovery reports Kubernetes TLSStore/IngressRoute, handled by kubernetes-api.
Certificate requirements
PEM with the leaf first, followed by intermediates in order. A separate matching unencrypted private key in PKCS#8, PKCS#1 RSA or SEC1 EC. The agent does not install DER, PFX or JKS.
RSA 2048/3072/4096 bits or ECDSA P-256/P-384. SAN must cover SNI and preserve the names served by the selected certificate. Wildcards cover one complete leftmost label; IP targets need IP SAN. No CN, fixed subject or friendly name is required.
The certificate must be valid and trusted for TLS server use. KU/EKU are optional; when present they must permit server use, including digitalSignature for modern handshakes and serverAuth in EKU. No fixed SAN or lifetime limit is declared. The Traefik process user must read the files; the agent retains required permissions and protects the key.