Skip to main content
2 video tutorials

Distribution overview

How modules work — Execute, DryRun, Validate, HealthCheck. Fan-out concurrency, batch sizing, post-distribution validation, and how distribution failures interact with renewal.

The module system​

Distribution is implemented as modules. CertAutoPilot ships twenty-one built-in modules — SSH, Kubernetes, IIS, WinRM, F5 BIG-IP, Citrix NetScaler, A10 Thunder, HashiCorp Vault, Huawei Cloud, Cloudflare, cPanel/WHM, MerlinCDN, AWS ACM, Azure Key Vault, Palo Alto PAN-OS, Fortinet FortiWeb, Fortinet FortiGate, Elchi, Webhook, Email/SMTP, Microsoft Exchange. Each module implements four operations:

OperationWhat it does
ExecutePush the certificate + key + chain to the target.
DryRunShow exactly what Execute would do, without doing it. Exposed as the distribution's Dry run action.
ValidateInterface method, currently unused. Post-deploy verification runs through the target's validation endpoints, not this method.
HealthCheckProbe reachability and credentials without deploying anything. See Health checks.

Rollback is not a module operation — there is no Rollback method on the interface. A rollback re-runs Execute with a previous retained certificate version. See Rollback.

Distribution 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.

Fan-out execution​

When a certificate has many targets — say, 80 SSH hosts — distribution can run fan-out: split into batches, run each batch concurrently. Fan-out is disabled by default (distribution_fanout_threshold: 0); set a positive threshold in Settings → General to enable it. Batch size defaults to 50 (distribution_fanout_batch_size), and SSH concurrency uses the module default of 10 unless overridden (distribution_ssh_max_concurrency).

Failures within a batch don't stop other batches. Each target gets its own result status — success, failed, partial or skipped — plus a fan-out state of pending_retry while a retry child is outstanding.

DryRun & approvals​

Dry run on a distribution (project operator, POST …/distributions/{distId}/dry-run) reports, per target, exactly what files would land where, what services would reload and what API calls would fire — without changing anything. An approval request does not carry a dry run: approvers see the proposed change itself, so run a dry run on the distribution before approving or executing when you want to see its effect.

A dry run resolves the same per-certificate overrides the real run would (target, group and Default overrides, PathSet/ActionSet selection, auto-generated object names), so the plan describes the run that would actually happen — not the target's defaults.

A dry run is bounded at 100 seconds in total. The IIS and WinRM modules check different hosts side by side (Exchange still checks its targets one after another) and shorten each target's own budget to what is left, so one slow host is reported as timed out on its own row while every other target still returns its plan. Each IIS and WinRM target also shows how long it took and, on hover, how long each remote round trip took — the quickest way to tell a slow host from a slow check.

Findings come back in two lists. Warnings are things to act on: something that will change, or a setting that will not work. Notes are what the preview could not determine — a remote system that will not report a fact is a limit of the preview, not a problem with the deployment, and mixing the two only teaches operators to skim the warnings. What each module reports:

ModuleThe preview says
IISEvery binding it would touch: replace (with the certificate on it today), already current, Central Certificate Store skipped, excluded by host header — plus the site's bindings and application pools
F5 BIG-IPThe object name and partition, one row per client-ssl profile (update, or skipped because the profile is missing), the chain it would install, and a warning when a profile already serves another CertAutoPilot certificate of the same key type
NetScalerThe certkey name, the file uploads, and whether it creates or updates in place — including how many vservers keep their bindings
KubernetesEvery Secret it would create or update, and the ones already current, plus each workload it would restart
AWS ACMWhether it creates or re-imports, what the ARN covers today (domain, status, expiry, how many resources use it) — and it refuses up front an ARN that ACM issued itself, which can never be imported over
CloudflareCreate or update, the hosts the certificate being replaced serves, and a warning when the zone's plan cannot hold a custom certificate at all
Azure Key VaultCreate or new version (with the reason), and a warning when the name belongs to another certificate
PAN-OSCreate or update of the named object, including material already sitting uncommitted in the candidate configuration
FortiWebFirmware and method, CA certificates to upload (intermediate / root), groups that will carry the chain, import / in-place update / reuse of the object, every hitless binding to move, deletes when delete_old_cert is on — warnings for policies left on an earlier version, an unbound certificate, skipped or unused placements and shared groups (the firmware line is a note); a run the deploy would refuse before writing (a policy without an intermediate group, a name conflict, a key-type change in a multi-certificate slot) shows the target as failed with the deploy's code
A10 ThunderThe upload or in-place replace of the file, each template entry and SNI entry it would set (a template it would create) and the save — warnings when an entry names a file CertAutoPilot did not write, when no virtual port would serve the file, when an SNI name is not covered, or when HA is configured; a refusal the deploy would make before writing (a file it does not own, a key-type change beside an entry of the new type, an SNI shape it does not write) shows the target as failed with the deploy's code
FortiGateIntermediate CA certificates to import, create or in-place update of the local certificate, and each VIP, SSL inspection profile and SSL VPN setting it would add — warnings when the name would take over a certificate CertAutoPilot did not create, when nothing would use the certificate, or when the target moved to another firewall or VDOM; a refusal the deploy would make before writing (name conflict, missing VIP or profile, profile in re-sign mode, VDOM not enabled) shows the target as failed with the deploy's code
ElchiPer version Elchi serves: create, update of the recorded secret by id, or nothing — and the refusal when a secret of that name was not created by CertAutoPilot for this certificate
Huawei CloudCreate or update of the ELB/WAF certificate object, resolved the same way the deploy resolves it; for CDN, whether the domain exists at all
ExchangeThe servers it would reach, the import and enable steps, the certificate OWA/ECP/EWS currently serves, and a warning when the certificate's key type — or a wildcard subject with POP/IMAP selected — cannot work
cPanel / WHMPer domain, the install — and on cPanel what certificate is on that domain today
SSH / WinRMPer file: create, or leave unchanged, compared against the file already on the host
SMTP / WebhookThe recipients or endpoint it would send to, proven by an actual probe

A preview never writes. When a lookup it needs is unavailable, it says so in a warning and keeps the rest of the plan rather than guessing.

Two rules of the project's approval policy (Settings → Approvals, changed only by an organization owner) decide whether an operator's distribution work needs approval — for all operators, or only selected users and groups (admins and owners always bypass):

  • Distribution actions (no approval by default) gates operator distribution link / update / unlink / execute / rollback. Only the manual operator action is gated — the scheduler's automatic post-renewal distribution sweep is not gated, so renewals keep flowing to their targets. A distribution that runs an ActionSet on SSH or WinRM targets needs the Admin role to execute or roll back by hand (an operator covered by this rule sends a request instead).
  • Configuration changes (all operators by default) gates operator edits to targets, target-groups, PathSets/ActionSets, module configurations, and project-variables.

See Approval workflow and Auth & RBAC.

Post-distribution validation​

After Execute, the worker runs every validation endpoint configured on the resolved targets: it opens a TLS connection and compares the served leaf certificate's SHA-256 fingerprint against the one just deployed.

Per-endpoint dial timeout defaults to 5 seconds with 3 attempts / 2-second delay; all configurable per endpoint. Validation is opt-in for every module: a target with no endpoints configured is not verified, and the worker caps a single target's whole validation phase at 5 minutes.

Which chain is deployed​

Every module deploys the chain stored with the certificate version: the one the certificate's chain choice asks for, or the CA's own chain when there is no choice. A distribution set to The CA's default chain deploys the chain exactly as the CA delivered it, whatever the certificate chooses.

Rollback​

A rollback re-deploys a previous retained certificate version — from the certificate's per-renewal artifact history — through the module's normal deploy path. One uniform mechanism, no per-module snapshots: all twenty-one modules support manual rollback (the two push modules, Webhook and SMTP, re-send the previous version), while auto-rollback covers the nineteen stateful modules only. Trigger it from the version picker on the Distribution tab or via the API; a per-distribution auto_rollback_on_failure toggle rolls back automatically when a run finishes failed/partial and at least one target changed. After a successful rollback the distribution's status is rolled_back and stays that way until the next renewal rolls forward. Details, eligibility rules, and the capability matrix: Rollback.

Distribution & renewal​

Renewal and distribution are decoupled: a renewal is successful the moment the new certificate is stored — distribution is then triggered automatically for every enabled distribution of the certificate. If a distribution fails, the renewal is NOT re-run; instead the failed distribution is retried by the distribution sweep (bounded automatic retries per certificate version), failure notifications fire, and the targets keep serving the previous certificate until a re-push succeeds or an operator re-runs the distribution manually.

API​

POST /api/v1/projects/{project}/targets
GET /api/v1/projects/{project}/certificates/{id}/distributions
POST /api/v1/projects/{project}/certificates/{id}/distributions/{distId}/execute
POST /api/v1/projects/{project}/certificates/{id}/distributions/{distId}/dry-run

See also​

note
A partial run is not retried automatically

Only a wholly failed distribution is re-armed by the renewal sweep. partial is excluded on purpose: some targets already have the certificate, and re-running would deploy to them again — re-executing ActionSets and service restarts that already succeeded. Re-run a partial distribution manually from the certificate's Distributions tab.

Video tutorials

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Deploy a Certificate to a Linux Server over SSHYouTube ↗
Automatic Redeploy After RenewalYouTube ↗