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, read-only 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.
Modules that implement the detailed variant return a per-target result list (name, address, healthy, error); others return a single pass/fail with the first error.
What each module checks
| Module | Probe | What passes |
|---|---|---|
| SSH | open SSH connection with the target's credential | TCP connect + SSH auth succeed |
| Kubernetes | list namespaces (limit 1) with the kubeconfig/token | API server reachable, credential accepted, minimal read RBAC |
| IIS | WinRM connect + run a trivial PowerShell probe | WinRM reachable, auth OK, remote PowerShell executes (exit 0, expected output) |
| WinRM (generic) | exec Write-Output "OK" over WinRM | transport reachable, auth OK, PowerShell executes |
| Webhook | HTTP HEAD to the base URL (10 s timeout) | endpoint answered at all — the status code is not evaluated |
| NetScaler | NITRO API ping (10 s timeout) | NSIP reachable, credential accepted |
| F5 BIG-IP | iControl REST version query (10 s timeout) | management endpoint reachable, credential accepted |
| Vault | authenticate with the target's credential | Vault reachable, login succeeds (detailed variant also reports mount reachability) |
| Huawei Cloud | ELB: ListCertificates with a dummy name filter; CDN: client init + domain_id presence check | region endpoint reachable, AK/SK accepted |
| SMTP | dial the relay, STARTTLS/SMTPS as configured, EHLO + QUIT — no AUTH attempted | relay reachable and speaks SMTP (deliberately does not test credentials, to avoid filling the relay's audit log with failed probes) |
| AWS ACM | acm:ListCertificates in the target region (10 s timeout) | region endpoint reachable, access key valid, list permission granted |
| MerlinCDN | authenticated GET on the target's distribution | API reachable, PAT + org/workspace headers accepted, distribution exists |
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, error message).
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 },
{ "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" }
]
}
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.
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
| Symptom | Likely cause |
|---|---|
| Connect / dial timeout | Firewall between backend and target, wrong host/port, target down. Test from the backend host, not your laptop. |
| Auth error | Wrong or rotated credential; for WinRM/IIS also check the auth type (NTLM vs Basic) matches the server config. |
| Only some targets red | Per-host issue (host down, per-host firewall rule, host-specific credential) — the module config itself is fine. |
| All targets red | Shared cause: expired credential, egress rule, DNS. |