Distribution overview
How modules work — Execute, DryRun, Validate, Rollback. Fan-out concurrency, batch sizing, post-distribution validation, and how distribution failures interact with renewal.
01The module system
Distribution is implemented as modules. CertAutoPilot ships ten built-in modules — SSH, Kubernetes, IIS, WinRM, F5 BIG-IP, Citrix NetScaler, HashiCorp Vault, Huawei Cloud, Webhook, Email/SMTP. Each module implements four operations:
| Operation | What it does |
|---|---|
Execute | Push the certificate + key + chain to the target. |
DryRun | Show exactly what Execute would do, without doing it. Used by approvals. |
Validate | Verify the certificate is now in place. TLS fingerprint check or module-specific equivalent. |
Rollback | Restore the previous certificate if Validate fails. |
02Distribution targets
A target is a (module, credential, location) tuple. Examples:
- SSH module + ssh-key credential +
nginx-prod-01:/etc/nginx/ssl/site.pem - Kubernetes module + kubeconfig +
cluster=prod / ns=apps / secret=tls-www - F5 module + iControl creds +
partition=Common / profile=clientssl-www
Targets are reusable — many certificates can attach the same target.
03Fan-out execution
When a certificate has many targets — say, 80 SSH hosts — distribution runs fan-out: split into batches, run each batch concurrently. Batch size is configurable per certificate (default 10) and per module (default cap 25).
Failures within a batch don't stop other batches. Each target gets its own per-target status: queued, running, validated, rolled-back, failed.
04DryRun & approvals
If approval is required, the operator's Submit produces a request with the DryRun output for every attached target. Approvers see exactly what files will land where, what services will reload, what API calls will fire — before they approve.
05Post-distribution validation
After Execute, the worker calls Validate. Most modules do the same thing: open a TLS connection to the target endpoint and confirm the certificate fingerprint matches the one we just deployed.
Per-endpoint dial timeout defaults to 5 seconds with 3 retries / 2-second delay; all configurable per endpoint. Some modules (Webhook, Email) skip Validate.
06Rollback
If Validate fails, Rollback runs. Each module knows how to restore the previous cert from a per-target backup that Execute took right before the swap. After rollback, the target's status is rolled-back and the certificate's overall distribution status is partial-failure.
Some targets cannot be rolled back atomically (e.g. Vault PKI mounts that have ratcheted forward). For those, Validate is conservative — it will refuse to roll back rather than risk a worse state.
07Distribution & renewal
A renewal is considered successful only after at least one distribution target validates. If every target failed, the renewal is recorded as distribution-failed, the renewal scheduler retries the whole flow on the standard backoff, and the certificate keeps the old material live until distribution succeeds.
08API
POST /api/v1/projects/{project}/distribution-targets
POST /api/v1/projects/{project}/certificates/{id}/distribute
POST /api/v1/projects/{project}/certificates/{id}/distribute?dry_run=true
GET /api/v1/projects/{project}/certificates/{id}/distribution-status