Skip to main content

Requirements & sizing

Host requirements and capacity planning: how many VMs, how much CPU, memory and disk for a given certificate count and discovery footprint, and which tunables actually move the numbers.

Nothing here is enforced

The installer checks the OS, the packages and that the HTTPS and backend ports are free (27017 is not checked) — it does not check CPU, memory or disk, and it will happily install onto an undersized host. The floors below are operational guidance, with the one hard exception called out under Minimum host: MongoDB does not run well under 4 GiB.

Minimum host​

Per host, for the standalone install (application + nginx + a local MongoDB):

MinimumNotes
Architecturex86-64 or arm64glibc only. Alpine via the Docker path.
CPU featuresx86-64: AVXMongoDB 5.0+ refuses to start without it (Illegal instruction). Any physical x86 CPU since 2011 has it; a virtual CPU may not — see the admonition below.
vCPU2The application is network-bound, not compute-bound — see Where the work goes.
Memory4 GiBMongoDB's WiredTiger cache alone takes roughly half of (RAM − 1 GiB). Below 4 GiB the database is the first thing to suffer.
Disk20 GiB SSDMostly MongoDB. See Storage for the arithmetic.
Free ports443 (or --port), 18181 loopback, 27017 when Mongo is local (not checked by the installer)Standalone lists the layout.
Virtual CPUs without AVX

Hypervisors often present a generic CPU model that hides AVX from the guest — Proxmox's default x86-64-v2-AES is one — and the local MongoDB then crashes on start with signal=ILL (Illegal instruction), with nothing else on the host looking wrong. Check with grep -c avx /proc/cpuinfo before installing; on Proxmox set the VM's CPU type to host (or x86-64-v3), on VMware/KVM/Hyper-V pick a CPU model or compatibility level that passes AVX through. This matters only for hosts that run MongoDB (standalone, or the replica-set members of a --nodes install); application-only hosts do not need it.

An application-only host — one that joins an existing cluster with --mongo=external, or the fourth and later nodes of a --nodes install — has no database to feed and runs comfortably in 2 vCPU / 2 GiB.

Distros, ports and the outbound destinations the product dials are covered by Standalone deployment, Installation and inbound network access and Outbound network access; this page is only about capacity.

Where the work goes​

Sizing follows the concurrency model, not the certificate count directly. Every CertAutoPilot process started as --mode=all — which is what both the standalone installer and the Helm chart run — contains three things in one binary:

  • The API, which does almost nothing expensive. Requests are small Mongo reads and writes.
  • Two worker lanes. A main worker (ACME, AD CS, notifications, discovery) and a dedicated distribution worker, each of which claims up to worker.max_concurrency jobs at a time (default 4). One host therefore runs up to 8 jobs concurrently, no matter how many certificates exist.
  • The scheduler, leader-elected across the cluster through a MongoDB lock, so exactly one host sweeps at a time regardless of cluster size. Default sweep interval 1 hour.

What that means in practice:

ActivityBound byCost shape
Issuance / renewalCertificate authority round-trips and DNS propagationWall-clock, not CPU. The phased DNS-01 flow deliberately releases its worker between polls, so a slow zone costs no lane.
Key generationKey typeECDSA P-256 (the default) is microseconds. RSA-4096 is the only routinely CPU-visible operation, and it runs once per renewal.
DistributionTarget device response timesOne job holds one distribution lane for up to distribution_execution_timeout_minutes (default 30). Per-device locks serialise anything that would conflict.
DiscoveryConcurrent TLS handshakesOne scan job holds one lane. Its connections are capped process-wide by worker.max_concurrent_discovery (default 50), so scans share a budget instead of multiplying.
DatabaseWorking-set sizeSee Storage. At a few thousand certificates the whole working set fits in cache on any of the profiles below.

The practical consequence: certificates buy you database, discovery buys you CPU. They are independent axes — size them separately.

Topology​

TopologyHostsMongoDBSurvivesUse when
Single VM1Local, standaloneNothing — host loss is an outageEvaluation, lab, one team, non-critical renewals
Multi-VM, external database2+Managed / existing replica setHost loss, if the database is replicatedYou already run MongoDB and want the app layer redundant
3-VM cluster (--nodes)33-member replica set caprs, installed for youLoss of any single host, including the database primaryThe default recommendation for production
3-VM cluster + app nodes3 + NReplica set on the first three onlySame, with more API/worker capacityDistribution or discovery throughput outgrows three hosts
KubernetesreplicaCount podsYours to supplyPod and node lossYou already run Kubernetes — see Helm chart

Why three, not two​

A two-host cluster with local databases is refused by the installer, and deliberately: MongoDB elects a primary by majority, and two members cannot form one when either dies. Three members tolerate the loss of one. The same number falls out of the application layer — the scheduler lock and every job claim are single-document atomic operations, so extra hosts are always safe, but below three there is no majority to elect anything.

Hosts four and upward run the application without a local mongod. They add API and worker capacity — eight more concurrent job lanes each — and nothing else. Add them when lanes are the constraint, not when the database is.

Full mechanics, firewall rules and failover behaviour: High availability.

Sizing profiles​

Per host. "Certificates" means certificates CertAutoPilot manages — the license cap is a separate, independent limit.

ProfileCertificatesDiscoveryTopologyvCPUMemoryDisk
Evaluation≤ 50Occasional /241 VM24 GiB20 GiB
Small production≤ 500A few /24s daily1 VM, or 3 for availability48 GiB50 GiB
Standard production≤ 2,500/22–/20 daily, CT feeds on3 VMs48 GiB100 GiB
Large / discovery-heavy≤ 2,500/16 sweeps, deep SNI, cipher enumeration3 VMs + app nodes816 GiB200 GiB

Two notes on reading that table:

  • The certificate column moves disk, not CPU. Going from 500 to 2,500 certificates roughly quintuples the database and changes nothing else, because renewals are paced by the scheduler and bounded by the worker lanes.
  • The discovery column moves CPU, not memory. A /16 sweep with cipher enumeration is the only workload in the product that can saturate a small host, and it does so through concurrent TLS handshakes — see Discovery sizing.

2,500 certificates is the validated capacity figure for the product; the profiles stop there because that is what has been measured, not because a larger number is refused.

Discovery sizing​

Discovery is the one workload worth sizing on its own, because its cost is set by settings rather than by inventory. It is also the most tightly bounded: every concurrency knob is capped process-wide, so no combination of sources can open an unbounded number of connections.

KnobWhereDefaultCeilingWhat it bounds
worker.max_concurrent_discoveryconfig.yaml50—Process-wide concurrent scan dials, across every source and every lane on the host
discovery.target_scan_max_parallel_hostsconfig.yaml / env18—Process-wide servers read at once by server certificate scans
discovery.target_scan_memory_mbconfig.yaml / env1024—Process-wide memory for the server certificate scan answers being worked on
concurrency_limitPer source20100Scan worker goroutines for that source. Actual network I/O still passes through the process-wide cap above.
max_targetsPer source51265,536Addresses × ports one run may touch. The ceiling is one /16 scanned on a single port.
timeout_secondsPer source530Dial timeout. A dead address costs this long; a tarpit cannot hold a slot longer.
Crawl deadlinePer source1,800 s—Hard wall-clock budget per run, kept under the worker's 30-minute stuck-job threshold
Cipher-enumeration budgetFixed15 min—Wall-clock cap on one source's whole cipher pass

So the realistic ceiling on one host is ~50 concurrent scan handshakes plus up to 64 concurrent cipher-enumeration handshakes — the cipher pass runs after the crawl drains, under its own process-wide limit of 64, and never holds a scan slot. The systemd unit ships LimitNOFILE=65536, so file descriptors are never the constraint; CPU for those handshakes is, which is why the discovery-heavy profile doubles the cores rather than the memory.

Memory does not scale with the size of the scan. Results are persisted as they arrive rather than buffered, so a run holds roughly one small entry per responding host:port — a /16 sweep that finds 50,000 live endpoints costs tens of megabytes, not gigabytes.

Server certificate scans ("Managed servers" sources) are bounded the same way: a worker process reads at most discovery.target_scan_max_parallel_hosts servers at once (default 18; each answer can be up to 64 MiB) and the answers being worked on share discovery.target_scan_memory_mb (default 1024; an answer takes about six times its size — MEASURED: 20,000 certificate files, a 23.5 MB answer, used 139 MB). With the defaults that is at most about 2.2 GiB per worker process, however many sources and runs are going. A server that waits until its run ends is reported Not reached and keeps what was found there before. On a small container (the Helm chart's default limit is 256 MiB) lower both, for example to 2 servers and 96 MiB. See the configuration reference.

Two optional per-source features add handshakes rather than concurrency: TLS version probing costs one extra 3-second handshake per endpoint, and cipher enumeration one connection per suite tested. Both lengthen a run; neither raises the ceilings above.

Storage​

MongoDB is the only thing that grows. The figures below are measured avgObjSize values from a running instance — use them as coefficients, not as promises.

CollectionBytes per documentGrows withBounded by
certificate_artifacts~10,500certificates × retained versionscert_history_max_versions (default 10)
certificate_private_keys~2,600certificates × distinct keysSame retention, pruned only when no retained artifact uses the key
certificates~1,000certificates—
discovered_endpoints~550live endpoints found180-day TTL after an endpoint disappears
discovered_certificates~970distinct certificates seen—
jobs~590renewals × jobs per renewal30-day TTL on terminal jobs
job_logs~165log lines30-day TTL
audit_logs~830operator and API actions30-day TTL
cert_eventssmalllifecycle events365-day TTL
notification_historysmallnotifications sent90-day TTL
scheduler_sweep_runs~290sweeps7-day TTL

Index overhead measured on the same instance is roughly 55–60% of data size. Budget total MongoDB footprint at about 1.6× the data figure.

Worked example​

2,500 certificates at default retention:

artifacts 2,500 × 10.5 KB × 10 versions ≈ 260 MB
private keys 2,500 × 2.6 KB × ~1–10 keys ≈ 7–65 MB
certificates 2,500 × 1.0 KB ≈ 2.5 MB
----------
data ≈ 270–330 MB
+ indexes (×1.6) ≈ 430–530 MB

Add the churn collections, all of which are TTL-bounded rather than cumulative: at a 47-day certificate lifetime and a 30-day renewal threshold, 2,500 certificates renew roughly 150 times a day, producing on the order of 1,000 job documents and 6,000 log lines daily — under 100 MB inside the 30-day window, indexes included. Discovery adds ~550 bytes per live endpoint.

A 2,500-certificate deployment is therefore well under 2 GiB of database. Disk goes to the operating system, the journal, and — if you enabled --enable-backup — seven nightly dumps, each roughly the size of the compressed data. The 50–200 GiB in the profile table is headroom for those and for growth, not a prediction of the data size.

Lowering cert_history_max_versions is the single most effective storage lever: it is a direct multiplier on the largest collection. Raising it is how you keep more rollback targets available, which is the trade.

Tunables that matter​

SettingWhereDefaultRangeRaise it when
worker.max_concurrencyConfig file / CERTAUTOPILOT_WORKER_MAX_CONCURRENCY4≥ 1Jobs queue while CPU sits idle. Applies to both lanes, so the real ceiling is 2× this per host.
distribution_fanout_thresholdSettings → General0 (off)0–500A distribution has more targets than one 30-minute job can finish. Splits it into batch children.
distribution_fanout_batch_sizeSettings → General500–200Batches finish too fast (raise) or time out (lower).
distribution_ssh_max_concurrencySettings → Generalmodule default 100–50SSH fan-outs are the bottleneck. Per-module concurrency is clamped to 1–50 everywhere.
distribution_windows_max_concurrencySettings → General80–32IIS deploys over many hosts are the bottleneck. Same-host targets stay serial whatever the value.
distribution_execution_timeout_minutesSettings → General305–120Slow appliances abort mid-run.
renewal_check_interval_minutesSettings → General60—Rarely. The sweep is cheap; the certificate authority is the slow part.
cert_history_max_versionsSettings → General10−1 (unlimited) – 100You need deeper rollback history, and you have the disk.
worker.max_concurrent_discoveryconfig.yaml only50≥ 1Scans are slow while the host has spare CPU. This is the process-wide handshake budget — raising a source's own concurrency_limit does nothing until this moves. The key is absent from the standalone template, so the CERTAUTOPILOT_* env var is silently ignored until you add it by hand (configuration reference).
concurrency_limit / max_targetsPer discovery source20 / 512≤ 100 / ≤ 65,536Scans take too long — but read Discovery sizing first.

Slow or large Windows estates​

IIS, Exchange and generic WinRM targets are driven over WinRM, where every command is several HTTP round trips (and NTLM adds a handshake to each). On slow links, busy hosts or large target counts, size these deliberately:

  • Execution timeout × batch. One job (or one fan-out child) has one execution timeout for all its targets. IIS works on up to distribution_windows_max_concurrency hosts at once, one target per host at a time; a target may take up to its target timeout (IIS: target_timeout_seconds, else five times the command timeout plus 30 s — 330 s by default). Rough ceiling for one job: execution timeout ÷ target budget × hosts at once. Fan-out shrinks its batches to that on its own; with fan-out off the job log warns.
  • Connect vs command timeout. The target's connect timeout bounds the TCP connect; every WinRM request then waits at least 60 seconds (or the connect timeout, if longer) for an answer. The command timeout bounds each remote command (IIS 60 s, Exchange 300 s). A timeout message says which one ran out: "could not connect … within N s" is the network, "accepted the connection but did not answer … within N s" is a slow host. Raise the one that fires — on a slow segment usually the command timeout, or IIS's target_timeout_seconds.
  • Kerberos: pin the KDC (kdc_host) on sites where DNS SRV lookups are slow; without it every request looks the KDC up again.
  • Exchange: each server gets its own budget (twice the command timeout plus 60 s for the service restart); a server the job has no time left for is reported "not attempted (time budget)" instead of timing out halfway. Validation after a restart is automatically more patient (30 s settle, 6 × 10 s) — set the endpoint's retries / retry_delay_ms yourself only if the web services take longer still to come back.
  • Health checks and Dry Run have fixed budgets (100 s for the whole check, 100 s for a dry run); on a very large or slow fleet some targets come back not checked — check those on their own.

Kubernetes​

The chart's shipped requests and limits — 100m/128Mi requested, 500m/256Mi limited — are sized for an API-shaped pod. They are not enough for a pod that wins a large discovery job or a wide distribution fan-out: the same process runs the workers. If you scan anything larger than a /24, raise the limits to at least 1 CPU / 1 GiB before you tune anything else.

Memory limits and the garbage collector. At startup CertAutoPilot reads the memory limit of its own cgroup — the pod's resources.limits.memory, a Docker --memory, or a systemd MemoryMax= — and tells the Go garbage collector to work harder once the heap reaches 80 % of it. Near the ceiling the process slows down instead of being OOM-killed. The startup log says which limit it found (Go soft memory limit set from the cgroup limit). With no limit (a plain VM install) nothing changes. To choose the value yourself, set the GOMEMLIMIT environment variable (for example GOMEMLIMIT=900MiB); an explicit value is always used as-is.

The chart runs --mode=all in every replica with a leader-elected scheduler, so replicaCount scales lanes exactly like adding VM nodes does — eight concurrent jobs per replica at the default concurrency. See Helm chart.

When to grow​

Signals, in the order they usually appear:

  1. Jobs sit in pending while CPU is idle — lane starvation. Raise worker.max_concurrency, then add application nodes.
  2. Distribution jobs hit the 30-minute timeout — turn on fan-out; the threshold defaults to off.
  3. Discovery runs report partial coverage — the crawl budget expired. Lower max_targets, split the source, or add cores.
  4. MongoDB read latency climbs — the working set no longer fits the WiredTiger cache. Add memory before adding hosts; a replica set does not make reads faster when they default to the primary.
  5. Disk growth tracks renewals — check cert_history_max_versions before buying disk.