Skip to main content
Video tutorial · 2:40

Module health checks

What the per-module health check verifies (connectivity + authentication, per target), how to run it from the UI or API, and what a green result does not guarantee.

What a health check is​

Every distribution module implements HealthCheck: a cheap probe run against all targets resolved from a module configuration. It answers one question per target — can CertAutoPilot reach this target and authenticate? — without touching any certificate material. The whole check is bounded to 100 seconds on the server — below the 120-second proxy timeout of the bundled Docker/Helm nginx, so the answer always arrives before the proxy gives up. Each Windows target also gets its own budget (IIS 45 s, Exchange 60 s, generic WinRM the connect timeout plus 35 s), shortened to what the whole check has left; a target that hits it reports how long it had, and a target the check had no time left to start is reported as not checked — run that target's own Test connection. Every per-target row carries duration_ms.

It changes nothing on the target, with two small exceptions. The IIS and Windows preflight writes a tiny test file into each temp directory it checks and deletes it at once, to prove they are writable. An Exchange check has to open an Exchange management session, which means uploading the service account's password to a temporary file on the server and deleting it afterwards. See Exchange.

Modules that implement the detailed variant return a per-target result list — name, address, healthy, the steps checked, the error, and warnings (conditions that do not stop a deploy but that you should know about); others return a single pass/fail with the first error. IIS, Exchange and Windows targets are checked up to five hosts at a time, never two targets of one host at once.

What each module checks​

ModuleProbeWhat passes
SSHopen SSH connection with the target's credentialTCP connect + SSH auth succeed
KubernetesGET /version on the API serverAPI server reachable and the client builds. It exercises no RBAC, so a missing Secret, restart or cleanup permission passes here and fails at deploy time instead.
IISWinRM connect + the preflight scriptWinRM reachable, auth OK, and the host can run a deploy: PowerShell 3 or later in Full Language mode, an administrator token (not UAC-filtered), the WebAdministration module, IIS (W3SVC) installed, Cert:\LocalMachine\My accessible, C:\Windows\Temp writable. Each missing prerequisite is reported with its fix (IIS_HOST_PREREQ, or IIS_MODULE_MISSING when WebAdministration is the only one). Warnings, which do not fail the check: a stopped W3SVC, less than 1 GB free on C:, a PowerShell older than the tested 5.1, and a MaxEnvelopeSizekb below 201 (with the largest transfer that still fits). Then the sites the target names (site_name / site_names, or the excluded_sites of an every-site placement): a site renamed in IIS makes the target unhealthy (IIS_SITE_RENAMED, naming the new name); a site that is simply not there is a warning (IIS_SITE_NOT_FOUND — a distribution override may name another site — or IIS_EXCLUDED_SITE_NOT_FOUND). It does not check bindings — use Dry run.
WinRM (generic)WinRM connect + the preflight scripttransport reachable, auth OK, and PowerShell 3 or later in Full Language mode (WINRM_HOST_PREREQ otherwise). Warnings, not failures: an account that is not an administrator or has a UAC-filtered token (this module can legitimately run as a non-administrator the host granted WinRS access to), an unwritable %TEMP%, a MaxEnvelopeSizekb below 201, a PowerShell older than 5.1, and less than 1 GB free. Not the PathSet paths or the ActionSet.
WebhookHTTP HEAD to the base URL (5 s timeout)endpoint answered at all — the status code is not evaluated
NetScalerNITRO API ping (5 s timeout)NSIP reachable, credential accepted; over HTTPS the served certificate's fingerprint is reported as tls_fingerprint_sha256:… (the value to pin) and a password sent without Verify TLS or a pin warns TLS_UNVERIFIED_PASSWORD
F5 BIG-IPiControl REST version query (5 s timeout)management endpoint reachable, credential accepted; over HTTPS the served certificate's fingerprint is reported as tls_fingerprint_sha256:… and a password sent without Verify TLS or a pin warns TLS_UNVERIFIED_PASSWORD
Vaultauthenticate with the target's credentialVault reachable, login succeeds (detailed variant also reports mount reachability)
Huawei CloudELB: ListCertificates with a dummy name filter; CDN: client init + domain_id presence check; WAF: client init against the region endpointregion endpoint reachable, AK/SK accepted
SMTPdial the relay, STARTTLS/SMTPS as configured, EHLO + QUIT — no AUTH attemptedrelay reachable and speaks SMTP (deliberately does not test credentials, to avoid filling the relay's audit log with failed probes)
AWS ACMacm:ListCertificates in the target region (5 s timeout)region endpoint reachable, access key valid, list permission granted
CloudflareZone read (GET /zones/{id}, resolving zone_name first)Cloudflare API reachable, API token valid and scoped to the zone; the zone's plan is reported, and a plan that cannot hold a custom certificate is named
Azure Key VaultAAD token acquisition + single-page certificate list (GET /certificates?maxresults=1) + one per-object read (GET /certificates/{name}, where 404 is the healthy answer)AAD credential valid, vault reachable, List and Get permissions granted, owning subscription active — a vault serves the list even when it refuses every per-object read
cPanel / WHMAuthenticated probe (cPanel installed-hosts list / WHM version)Host reachable on the API port, username + API token valid
MerlinCDNauthenticated GET on the target's distributionAPI reachable, PAT + org/workspace headers accepted, distribution exists
ExchangeWinRM connect + load EMS + Get-ExchangeServer/Get-ExchangeCertificateWinRM reachable, credential accepted, Exchange Management Shell available, certificate list readable (reported as its own check line)
PAN-OSauthenticate against the XML API + read system info (reports the PAN-OS version)management interface reachable, credential accepted; the served certificate's fingerprint is reported as tls_fingerprint_sha256:… (the value to pin) and a password sent without Verify TLS or a pin warns TLS_UNVERIFIED_PASSWORD; fails when the target sets a vsys but multi-vsys is disabled
FortiWebGET cmdb/system/global + GET cmdb/system/ha + GET system/status.systemstatus per target; every target first sends GET cmdb/system/global without an ADOM (once per appliance and check) to test the password. A refused password is not tried again for any target on the appliance with that username, a refused ADOM only stops the targets naming it, and after one refused login fewer than the appliance's lockout threshold nothing more is sent to itREST API reachable, credential accepted in the target's ADOM; the served certificate's fingerprint is reported as tls_fingerprint_sha256:… (the value to pin) and a password sent without Verify TLS or a pin warns TLS_UNVERIFIED_PASSWORD; a target naming an ADOM on an appliance without ADOMs is unhealthy (FORTIWEB_VALIDATION); reports the hostname, the ADOM (adom:<name> or adom:disabled), firmware and method (in_place 8.0.7+ / repoint); firmware before 8.0.7 is a warning (the HA mode is reported as ha:<mode>); a firmware version that cannot be read makes the target unhealthy (a deploy stops on it too)
A10 ThunderaXAPI login + partition + version/oper + slb/ssl-cert/oper + HA state per target (20-second budget); after a refused login nothing more is sent to that device in the checkLogin accepted, certificate list readable; reports acos:, serial:, partition:, ha: and the served certificate's fingerprint as tls_fingerprint_sha256:…; aVCS / VRRP-A configured is warned (A10_HA_UNKNOWN)
FortiGateGET monitor/system/status + GET cmdb/vpn.certificate/local + GET cmdb/system/global per target (15-second budget); after a refused token nothing more is sent to that firewall in the checkREST API reachable, token accepted, certificate list readable; reports version:, serial:, vdom: and the served certificate's fingerprint as tls_fingerprint_sha256:… (the value to pin); a target naming a VDOM while VDOMs are disabled is unhealthy
ElchiPOST /auth/login, then the versions Elchi serves (/api/v3/setting/maintenance/cleanup/versions — with an Editor account the project's listeners and clusters) and GET /api/v3/xds/secrets?project=&limit=1the account logs in without a one-time code, sees the project and its versions

Running a health check​

From the UI: Settings → Distribution → Modules → Health Check button on the module configuration row. A modal shows the per-target outcome (address, healthy/unhealthy, the steps checked, the error message, and any warnings). A target's own Test connection button runs the same check for that target alone.

From the API (project Admin role required):

POST /api/v1/projects/{project}/modules/{id}/health

Response:

{
"healthy": false,
"targets": [
{ "name": "nginx-prod-01", "address": "10.0.4.11:22", "healthy": true, "duration_ms": 412 },
{ "name": "nginx-prod-02", "address": "10.0.4.12:22", "healthy": false,
"error": "SSH connect to 10.0.4.12:22: dial tcp: i/o timeout" },
{ "name": "web-iis", "address": "win01.corp.local:5986", "healthy": true,
"checks": ["connect", "host prerequisites"],
"warnings": ["the IIS service (W3SVC) is Stopped — bindings can still be updated, but the sites are not serving"],
"duration_ms": 3120 },
{ "name": "web-iis-40", "address": "win40.corp.local:5986", "healthy": false,
"error": "not checked: the health check ran out of its overall time budget — check this target on its own" }
]
}

What it does NOT verify​

A green health check means reachable + authenticated — nothing more. It does not verify:

  • Write permissions — the SSH user may connect fine but lack write access to the PathSet directories; the Kubernetes token may list namespaces but be forbidden from updating Secrets; the AWS key may list certificates but be denied acm:ImportCertificate.
  • Paths and resources — PathSet directories, IIS site names, Vault mount paths (simple check), NetScaler certkey names, Webhook response semantics (any HTTP answer passes, even a 500).
  • Post-deploy actions — ActionSet commands, sudo rules, service reload permissions.
  • SMTP authentication — by design (see table above).

Use DryRun on the distribution for a deeper pre-flight: it connects with the real config and reports exactly what Execute would do per target.

Health check is a snapshot

The check runs on demand only — it is not scheduled. A target that was green last week can still fail tonight's renewal distribution. Treat it as a bring-up and troubleshooting tool, not as monitoring.

Interpreting failures​

SymptomLikely cause
Connect / dial timeoutFirewall between backend and target, wrong host/port, target down. Test from the backend host, not your laptop. For WinRM a deploy or dry run says which half timed out: "could not connect … within N s" (nothing answered the port) or "accepted the connection but did not answer … within N s" (the host is reachable but slow). A health check stops each host's preflight after 30 s; a host that accepts the connection and then stays silent then reads "… accepted the connection but did not answer the WinRM request within the N s this step had" (or "the Kerberos login … did not answer" when the domain's KDC was the slow part).
"not checked: … overall time budget"The check ran out of its 100 seconds before it reached this target (a slow fleet). Run the target's own Test connection.
Auth errorWrong or rotated credential; for WinRM/IIS also check the auth type (NTLM vs Basic) matches the server config.
Only some targets redPer-host issue (host down, per-host firewall rule, host-specific credential) — the module config itself is fine.
All targets redShared cause: expired credential, egress rule, DNS.

See also​

Running a check​

Two routes exist: POST /projects/{project}/modules/{id}/health probes every target of a module config, and POST /projects/{project}/targets/{id}/health probes exactly one target. Both are project admin actions and neither runs automatically when a target is saved.

Video tutorial

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

Target Groups, Health Checks and Fan-Out DeploymentsYouTube ↗