shankar0123
082b8cf660
Extracts the file-based deploy target connectors: - haproxy.md (107 lines) — combined-PEM (cert+chain+key) deploy with haproxy -c validate; multi-frontend + crt-list directory guidance - traefik.md (105 lines) — file-provider zero-reload deploy; file watcher latency notes; mixing with built-in ACME guidance - caddy.md (100 lines) — admin API mode (recommended) vs file mode; admin-API exposure threat model - envoy.md (112 lines) — file SDS mode (recommended) vs static bootstrap; service-mesh interactions - postfix.md (175 lines) — dual-mode (Postfix MTA / Dovecot IMAPS) connector with daemon-specific quirks (STARTTLS chain expectations, no shared session cache); Bundle 11 test pins Index forward-list expanded to enumerate all 10 target connectors (5 from Phase 4 structural + 5 from this batch) in alphabetical order. This is part 3 of 4 for the Phase 4 follow-on (per-connector page extraction) tracked in cowork/docs-overhaul-phase-2-restructure-2026-05-04/log.md. Net add: 5 files, 599 lines. No content removed from index.md.
3.2 KiB
Caddy Connector — Operator Deep-Dive
Last reviewed: 2026-05-05
Operator-grade documentation for the Caddy target connector. For the connector-development context (interface contract, registry, atomic deploy primitive shared across all targets), see the connector index.
Overview
The Caddy connector supports two deployment modes:
- API mode (recommended). Posts the certificate directly to Caddy's admin API for zero-downtime hot reload.
- File mode (fallback). Writes cert and key files to disk, relying on Caddy's built-in file watcher or a manual reload.
Implementation lives at internal/connector/target/caddy/.
When to use this connector
Use the Caddy connector when:
- Caddy fronts your services and you want certctl-managed certs rather than letting Caddy run its own ACME client.
- You want zero-downtime hot reload via Caddy's admin API.
Look elsewhere when:
- You'd rather Caddy keep running its own ACME client — point it at certctl's ACME server (see migration/acme-from-caddy.md) for the cleanest pattern.
Configuration
{
"mode": "api",
"admin_api": "http://localhost:2019",
"cert_dir": "/etc/caddy/certs",
"cert_file": "site.crt",
"key_file": "site.key"
}
When mode is "api", the connector posts the certificate to
the admin API endpoint. When mode is "file", it writes files
to cert_dir (same pattern as Traefik). The admin_api field is
ignored in file mode.
Mode trade-offs
API mode
- Zero-downtime hot reload via
POST /loador certificate-specific endpoints. - Requires Caddy's admin API to be enabled and reachable from the deployment agent.
- Best fit for production deployments where Caddy is configured with an admin endpoint.
File mode
- Writes cert and key files to
cert_dir; Caddy picks them up via its file watcher or on next config reload. - Use when the admin API isn't available or when Caddy is configured to read certificates from disk.
- Behaviorally equivalent to the Traefik connector.
Deploy contract
API mode bypasses the Bundle I file-write deploy primitive and talks directly to the Caddy admin API. File mode follows the standard atomic-write + verify path (idempotency check → backup → atomic write → optional reload → post-deploy TLS verify).
Operator playbook
Admin API exposure
Caddy's admin API is an unauthenticated control surface by
default. In API mode, ensure the admin API is bound to a
loopback or trusted network — exposing it to the public would
let anyone reload Caddy's config. Run the agent on the same host
as Caddy and use http://localhost:2019 for the safest posture.
Falling back to file mode
If the admin API is intermittently unreachable, switch the
target's mode to file via PUT /api/v1/targets/{id}. The
deploy still lands; reload behaviour is whatever the operator's
Caddy config does with file changes.
Related docs
- Connector index — interface contract, registry, deploy primitive
- Traefik — comparable file-provider target
- Migration: point Caddy at certctl's ACME — alternative pattern when Caddy should keep its ACME client