mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:11:29 +00:00
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.
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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](index.md).
|
|
|
|
## 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](../../migration/acme-from-caddy.md))
|
|
for the cleanest pattern.
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
{
|
|
"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 /load` or
|
|
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](traefik.md) 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](index.md) — interface contract, registry, deploy primitive
|
|
- [Traefik](traefik.md) — comparable file-provider target
|
|
- [Migration: point Caddy at certctl's ACME](../../migration/acme-from-caddy.md) — alternative pattern when Caddy should keep its ACME client
|