Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (54 loc) · 3.93 KB

CLAUDE.md

File metadata and controls

70 lines (54 loc) · 3.93 KB
Raw

Iterator

Event-driven automation tool that bridges Prometheus Alertmanager with Terraform — receives alert webhooks and executes Terraform modules in response.

Build & Test

make build        # CGO_ENABLED=0 linux/amd64 binary → ./build/iterator
make test         # go test -race with coverage
make lint         # golangci-lint
make docker-build # builds container (reads VERSION file for tag)
make ci           # mod → inst → gen → spell → test → build → docker-build

Architecture

Entry point flow: main.go → cli.NewApp() (cobra) → bootstrap.BootstrapIterator() → server.NewServer().Start()

Config pipeline: HCL input (/etc/iterator/config.hcl default, -f flag) → parsed via hashicorp/hcl/v2 in config.LoadConfig() → rendered to YAML (config.RenderConfig()) → read back as config.Config with command definitions.

Request flow (firing alert):

  1. Alertmanager POST → handleWebhook() unmarshals template.Data
  2. Per alert: amFiring() matches commands by labels, checks CanRun() (fingerprint dedup)
  3. instrument() runs command, tracks metrics, persists fingerprint data (file or Consul KV)

Request flow (resolved alert):

  1. amResolved() reads fingerprint data, runs terraform destroy (unless sawtooth scheduling)
  2. Cleans up fingerprint storage, closes fingerprint channel

Key Packages

Package Purpose
packages/cli Cobra CLI setup, release subcommand
packages/bootstrap Init sequence: storage, terraform, config render, server start
packages/server HTTP handlers, alert dispatch, metrics, fingerprint tracking
packages/config HCL parsing (InitConfig), YAML read (Config), render
packages/command Command execution, label matching, fingerprint generation, signal handling
packages/chanmap Thread-safe map of fingerprint → channel (for signaling running commands)
packages/countermap Thread-safe map of fingerprint → count (for max concurrent enforcement)
packages/terraform Terraform/Terragrunt execution (apply/destroy)
packages/consul Consul KV storage backend for fingerprint data
packages/lifecycle Release/sawtooth scheduling lifecycle management
packages/logger Structured logging with JSON/YAML output
packages/stats Active alert status tracking
packages/storage Data directory initialization

HTTP Endpoints

  • POST / — Alertmanager webhook receiver (main entry point)
  • POST /release — Trigger terraform destroy for a named alert (sawtooth release)
  • GET /metrics — Prometheus metrics (iterator_process_duration_seconds, iterator_processes_current, iterator_errors_total, iterator_signalled_total, iterator_skipped_total)
  • GET /_health — Health check

Key Patterns

  • Fingerprint dedup: Each alert+command produces a fingerprint. countermap tracks active count per fingerprint; chanmap maps fingerprint to quit channel. Command.Max limits concurrent runs per fingerprint.
  • Terraform scheduling modes: default runs destroy on resolve; sawtooth skips auto-destroy (released manually via /release endpoint or CLI).
  • Terraform drivers: Supports both terraform (-chdir=) and terragrunt (--terragrunt-working-dir).
  • Storage backends: File-based (default, writes JSON to {data_dir}/process/alerts/) or Consul KV.
  • Alert env vars: Alert data passed to commands as TF_VAR_ITERATOR_ALERT_* environment variables.

Code Conventions

  • Go 1.21.4, module github.com/cloudputation/iterator
  • Logging via packages/logger (wraps hclog): log.Info(), log.Error(), log.Fatal(), log.Debug()
  • Error handling: return errors up the stack; log.Fatal() for unrecoverable; HTTP 500 for webhook errors
  • Tests live in tests/go_tests/ (not colocated with packages)
  • Config default port: 9595
  • HCL config blocks: server {} and task {} with condition "label-match" {} sub-blocks