Caching

Ignition can cache the results of check() calls to skip redundant SSH round-trips on repeated runs.

Purpose

Every resource check() call runs one or more SSH commands to inspect remote state. For large inventories or frequent checks, this adds up. The cache stores check results locally so subsequent runs can skip the SSH calls for recently-verified resources.

Enabling caching

ignition run --check deploy.ts @web --inventory hosts.ts --cache

How it works

1. Before running check(), Ignition looks up the cache using a key derived from: host, resource type, resource name, and input.
2. If a cache hit is found and the entry is within TTL, the cached result is used without SSH.
3. If no hit or expired, check() runs normally and the result is cached.
4. Cache hits are reported in the output with timing.

Cache key structure

Each cache entry is keyed by:

• Hostname, port, user
• Resource type and name
• Serialized input (deterministic JSON)
• Internal cache version constant (CACHE_VERSION), bumped manually when cache semantics change

This means the cache only hits when the exact same resource with the exact same input is checked against the same host.

Cache storage

Cache entries are persisted to disk as JSON at .ignition/check-cache.json. This file is created automatically when --cache is enabled.

Limitations

• Check mode only — caching only applies during check(). Apply mode always runs a fresh check.
• Non-authoritative — the cache assumes remote state hasn't changed since the last check. If someone modifies the server between runs, the cache may be stale.
• TTL-based expiry — entries expire after the configured TTL (default 10 minutes). There's no event-based invalidation.
• Local to the machine — the cache file is not shared across machines.

When to use

• Repeated checks — running ignition run --check multiple times while iterating on a recipe
• Large inventories — checking 50+ hosts where most resources are already in desired state
• CI pipelines — speed up repeated ignition run --check runs in the same pipeline

Clearing the cache

# Clear before running
ignition run --check deploy.ts @web --cache --cache-clear

# Or delete the file directly
rm -rf .ignition/check-cache.json