feat(provisioning): provision correlation rules from KEEP_CORRELATION_RULES

[aditya-786]

Why are these changes needed?

The startup provisioner (keep/api/config.py:provision_resources) configures providers, workflows, dashboards, deduplication rules, and mapping rules from Helm values, but correlation (rules-engine) rules were left out. Today the only ways to create one are the UI, the SDK, or POST /rules, so a GitOps deployment cannot declare the alert grouping rule next to the workflow that uses the same CEL filter, and operators have to POST /rules after every cluster bootstrap.

This adds provision_correlation_rules_from_env, giving correlation rules the same env-driven provisioning the other resources already have. Closes #6563.

What changed

• keep/api/bl/correlation_rules_provisioning.py (new): provision_correlation_rules_from_env(tenant_id), mirroring provision_deduplication_rules_from_env. KEEP_CORRELATION_RULES holds a JSON array (or a path to a .json file, dispatched by the same regex the dedup provisioner uses) of rule specs in the POST /rules schema (ruleName, celQuery, sqlQuery, timeframeInSeconds, timeUnit, groupingCriteria, createOn, resolveOn, incidentNameTemplate, incidentPrefix, threshold, requireApprove).
• On every startup the DB is reconciled to the env: upsert by ruleName, delete provisioned rules that are no longer present, and never touch UI-created rules (is_provisioned=False). Unsetting the env var deprovisions everything the provisioner owns. Rolling restarts are idempotent.
• Each celQuery is compiled at provision time; a spec that is missing a required field or has an unparseable CEL is logged and skipped, so one bad rule does not block the others.
• is_provisioned column on Rule + Alembic migration b3f1c9a24d70 (on the current head 67ff7efffed4), tracking which rules the provisioner owns. Mirrors the flag added to MappingRule.
• db.create_rule gains an is_provisioned=False parameter (same shape create_deduplication_rule already has).
• provision_resources() calls the new function right after provision_mapping_rules_from_env.

Example values.yaml:

keep:
  backend:
    env:
      - name: KEEP_CORRELATION_RULES
        value: |
          [
            {
              "ruleName": "critical-alerts-correlation",
              "celQuery": "severity == \"critical\" && !name.startsWith(\"Data\")",
              "sqlQuery": { "sql": "severity = :severity", "params": { "severity": "critical" } },
              "timeframeInSeconds": 600,
              "timeUnit": "seconds",
              "createOn": "any",
              "resolveOn": "never",
              "threshold": 1
            }
          ]

Notes on scope

• The Helm chart lives in the separate keephq/helm-charts repo, so exposing a correlationRules key in the chart templates is a companion change there; this PR is the backend that reads the env var (same split as the existing dedup/mapping provisioning).
• On the matches() footgun the issue raises: the pinned cel-python in this repo does evaluate name.matches('^Foo') (returns a bool), so that specific case does not reproduce here. Provision-time validation therefore compiles the CEL to catch genuine parse errors rather than attempting a trial evaluation, which would false-negative on any rule referencing fields absent from a synthetic payload.

Checks

• I've made sure the tests are passing.
• Testing Strategy
  • Unit tests

tests/test_correlation_rules_provisioning.py (11 tests, mirroring the mapping/dedup provisioning tests): create, multiple, idempotent, update-in-place, deprovision-on-removal, deprovision-on-unset, leave-UI-rules-untouched, skip-invalid-CEL, skip-missing-field, load-from-.json-file, and clean no-op. All pass locally; the rules-engine suite (tests/test_rules_engine.py) stays green.

[apercivall]

We reviewed this PR, ran its tests, and deployed it on 0.54.3 in a self-hosted single-tenant install, where it does what it says — correlation rules that previously existed only as a database row are now declared in configuration and reconciled on every start. Thanks for writing it.

Some findings from reviewing and running it, in case they help it move.

The red checks are not this PR. All three failures are tests/e2e_tests/incidents_alerts_tests/test_filtering_sort_search_on_alerts.py — a Playwright strict-mode locator violation ([data-testid='facet'] matching two elements) and a 10s wait_for_selector timeout. Unrelated to provisioning; unit-tests and integration-tests pass. A rebase would probably clear them.

groupDescription is applied at creation and silently dropped on update. _create_correlation_rule passes it; _update_correlation_rule cannot, because db.update_rule has no such parameter — and the PUT /rules route never sends one either, so this is pre-existing and the PR inherits it. The effect is that editing groupDescription in KEEP_CORRELATION_RULES applies the first time the rule is created and is ignored ever after, which is the failure mode provisioning is meant to remove.

What worked for us was giving update_rule a group_description parameter defaulting to a sentinel rather than None:

_UNCHANGED = object()

def update_rule(..., assignee=None, group_description=_UNCHANGED):
    ...
    if group_description is not _UNCHANGED:
        rule.group_description = group_description

The sentinel matters: with a plain =None default, the route — which does not pass the field — would blank the description on every edit made in the UI.

A threshold of 0 aborts startup provisioning for every rule after it. _validate_rule_to_provision does not check it, Rule.threshold carries CheckConstraint("threshold>0"), and the failing commit happens outside the per-rule try, so it propagates out of provision_resources(). The POST /rules handler rejects 0 with its own check; RuleCreateDto does not. Suggest:

threshold = rule_to_provision.get("threshold", 1)
if isinstance(threshold, bool) or not isinstance(threshold, int) or threshold <= 0:
    raise ValueError("'threshold' must be a positive integer")

bool excluded explicitly since True is an int in Python and would pass a naive > 0.

Docstring vs. behaviour on paths. get_correlation_rules_to_provision documents "an absolute/relative path to a .json file", but the regex — inherited from the deduplication provisioner — only matches /, ./ and ../ prefixes. A bare config/rules.json falls through to json.loads and raises during startup. Worth either widening the check or narrowing the docstring; the same is true of the deduplication provisioner it was copied from.

One adoption note for anyone deploying this, which might be worth a line in the PR description: the provisioner only manages rules with is_provisioned = true, so an existing UI-created rule is not adopted by a matching ruleName — you get a second rule matching the same alerts. And the column does not exist until the migration has run, so the flag cannot be set beforehand. We are rolling it out in two steps for that reason: deploy with the env var unset (verified a clean no-op — No correlation rules to provision and none currently provisioned), then set the flag on the pre-existing row so the provisioner updates it in place rather than creating a twin, then add the declaration.

The migration applied cleanly on the current single head (67ff7efffed4) against PostgreSQL, and the full non-integration suite passes with the two changes above plus tests for them.