gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-09 18:38:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(postfix): add Mode=postfix vs Mode=dovecot decision matrix subsection

Browse Source 
Closes Top-10 fix #9 of the 2026-05-02 deployment-target audit
re-run (see cowork/deployment-target-audit-2026-05-02-rerun/
RESULTS.md). Pre-fix, the Postfix connector's docs in
docs/connectors.md described the connector as a single
"Postfix / Dovecot" target without explicit guidance on when to
use Mode=postfix vs Mode=dovecot. Operators with a mail server
running both Postfix (MTA, port 25) and Dovecot (IMAPS, port
993) had to read source to figure out the dual-deploy pattern.

Bundle 11 (commit 88e8881) added test pin for Mode=dovecot
(TestPostfix_Atomic_DovecotMode_HappyPath +
TestPostfix_Atomic_DovecotMode_VerifyFails_Rollback). This
commit lands the operator-facing doc that complements the test:

1. New "Choosing Mode=postfix vs Mode=dovecot" subsection in
   docs/connectors.md "Built-in: Postfix / Dovecot" section.
   Covers:
   - When to use each mode (MTA on 25 vs IMAPS on 993).
   - Daemon-specific defaults (cert_path, key_path,
     validate_command, reload_command) cited verbatim from
     internal/connector/target/postfix/postfix.go applyDefaults.
   - Note that postfix is the default when mode is unset.
   - Post-deploy verify endpoint is operator-supplied, NOT a
     per-mode default (the connector does not bake in
     port 25 / 993 — operators set post_deploy_verify.endpoint
     themselves to point at their daemon's listener).
   - Dual-deploy pattern for hosts running both daemons (two
     separate targets; byte-equal cert hits SHA-256
     idempotency on subsequent renewals; targets are independent
     in the scheduler so one reload failing rolls back that
     target only).
   - Shared-cert-via-symlink pattern (atomic-write os.Rename
     follows symlinks).
   - Daemon-specific quirks (Postfix STARTTLS chain
     requirements for external MTA validation; Dovecot IMAPS
     client-facing chain shipping; reload independence).
   - Test pin reference (Bundle 11 commit hash + dovecot test
     names; postfix-mode equivalent test names).

2. Forward-pointer footnote in docs/deployment-atomicity.md
   Section 3 "Per-connector atomic contract" pointing at the
   new subsection.

No code changes; no test changes; doc-only commit.

Verified locally:
- All defaults cited verbatim from postfix.go::applyDefaults
  (cert_path, key_path, validate_command, reload_command).
- Bundle 11 test names verified to exist in
  internal/connector/target/postfix/postfix_atomic_test.go
  (TestPostfix_Atomic_DovecotMode_HappyPath at L272,
  TestPostfix_Atomic_DovecotMode_VerifyFails_Rollback at L354).
- Spec's claim of "verify port 25 / 993 default" was incorrect:
  the connector does not bake in a per-mode verify port.
  Doc reflects ground truth.

Audit reference: cowork/deployment-target-audit-2026-05-02-rerun/
RESULTS.md Top-10 fix #9.
This commit is contained in:
shankar0123
2026-05-02 22:46:44 +00:00
parent f0d91fde39
commit e05da7d136
2 changed files with 48 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment-atomicity.md
+5
View File
@@ -134,6 +134,11 @@ Apply's algorithm:
| javakeystore | (`keytool -list`) | (`keytool -importkeystore`) | (admin probe) | keytool snapshot; rollback via `keytool -delete` + re-import |
| k8ssecret | (V2 blocker — see note below) | (V2 blocker — see note below) | (V2 blocker — see note below) | **V2 blocker — Bundle 2 of the 2026-05-02 deployment-target audit.** Production `realK8sClient` at `internal/connector/target/k8ssecret/k8ssecret.go:397-420` is a stub (every method returns `"real Kubernetes client not implemented — use NewWithClient for tests"`). The SHA-256 post-deploy verify and kubelet sync poll are designed but not yet implemented; production deploys to a real cluster fail with "not implemented" until Bundle 2 lands. Test mocks via `NewWithClient` work today. Tracking prompt: `cowork/deployment-target-audit-2026-05-02/k8s-real-client-prompt.md`. |
> **Postfix vs Dovecot mode**: see "Choosing Mode=postfix vs Mode=dovecot" in
> `docs/connectors.md` for the per-mode defaults (cert/key paths, validate +
> reload commands), the dual-deploy guidance for mail servers running both
> daemons, and the test-pin reference (Bundle 11 commit `88e8881`).
## 4. Post-deploy TLS verification
Frozen decision 0.3 (deploy-hardening I): post-deploy verify is