Auto-Rotation Watchdog#

Added in v0.5. Continuously monitors three signals and either alerts or fires infraguard rotate automatically when any of them crosses its threshold:

  1. Burn score rising above burn_threshold and staying there for burn_window seconds.
  2. TLS certificate within cert_days_before days of expiry.
  3. Cloud spend above cost_cap_usd (opt-in provider integration).

Configure#

Add a watchdog: block to config.yaml:

watchdog:
  enabled: true
  poll_interval: 300          # seconds between checks
  burn_threshold: 0.8
  burn_window: 900            # score must stay high this long
  cert_days_before: 14        # rotate 14 days before LE expiry
  cost_cap_usd: null          # disable cost check
  auto_rotate: true           # false = alert only, no rotation

Alert-only mode#

Set auto_rotate: false if you want the watchdog to page you but never touch cloud APIs. The watchdog emits a RequestEvent with filter_reason="burn_threshold_crossed" (or cert_expiring, etc.), so the alerting plugins fire in the normal way:

plugins:
  - infraguard.plugins.builtin.pagerduty
  - infraguard.plugins.builtin.slack

plugin_settings:
  pagerduty:
    options:
      integration_key: "${PAGERDUTY_KEY}"
      event_types: [burn_threshold_crossed, cert_expiring, all_upstreams_failed]

What triggers a rotation#

The watchdog logs each check at DEBUG. A rotation fires when either:

  • Burn score has been continuously above burn_threshold for at least burn_window seconds. Transient spikes do NOT rotate.
  • Any listener’s TLS cert is under cert_days_before days from expiry.

What does NOT happen#

  • Cloud billing checks require provider-specific API modules that are not shipped. cost_cap_usd accepts the value but the check is a documented follow-up.
  • Rotation itself delegates to the existing RotationManager (blue-green flow, provider-specific Terraform / Pulumi). The watchdog never speaks to cloud APIs directly.

See infrastructure-rotation for the underlying rotation flow.