PagerDuty Migrator: Add filtering capabilities and fix user notification rule preservation

[joeyorlando]

This PR adds filtering capabilities to the PagerDuty migrator tool and fixes user notification rule preservation behavior.

Closes https://github.com/grafana/irm/issues/612

Changes

1. Added Resource Filtering

Added the ability to filter PagerDuty resources during migration based on:

• Team membership
• User association
• Name patterns (using regex)

New environment variables for filtering:

PAGERDUTY_FILTER_TEAM
PAGERDUTY_FILTER_USERS
PAGERDUTY_FILTER_SCHEDULE_REGEX
PAGERDUTY_FILTER_ESCALATION_POLICY_REGEX
PAGERDUTY_FILTER_INTEGRATION_REGEX

Example Usage

Filter by team:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="plan" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PAGERDUTY_FILTER_TEAM="SRE Team" \
oncall-migrator

Filter by specific users:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="plan" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PAGERDUTY_FILTER_USERS="P123ABC,P456DEF" \
oncall-migrator

Filter schedules by name pattern:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="plan" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PAGERDUTY_FILTER_SCHEDULE_REGEX="^(Primary|Secondary)" \
oncall-migrator

Filter escalation policies by name pattern:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="plan" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PAGERDUTY_FILTER_ESCALATION_POLICY_REGEX="^Prod" \
oncall-migrator

Filter integrations by name pattern:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="plan" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PAGERDUTY_FILTER_INTEGRATION_REGEX="Prometheus$" \
oncall-migrator

2. Fixed User Notification Rule Preservation

Introduces a PRESERVE_EXISTING_USER_NOTIFICATION_RULES config (default of true). The migrator now:

• does not delete user notification rules in Grafana OnCall, if the Grafana user already has some defined, AND PRESERVE_EXISTING_USER_NOTIFICATION_RULES is True
  • if the Grafana user has no personal notification rules defined in OnCall, we will create them
• deletes existing user notification rules, and creates new ones, in Grafana OnCall, if PRESERVE_EXISTING_USER_NOTIFICATION_RULES is False
  • basically make sure that the state in Grafana OnCall matches the latest state in PagerDuty
• Improves logging to clearly indicate when rules are being preserved

Example Usage

Preserve existing notification policies (default):

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="migrate" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
oncall-migrator

Replace existing notification policies:

docker run --rm \
-e MIGRATING_FROM="pagerduty" \
-e MODE="migrate" \
-e ONCALL_API_URL="<your-oncall-api-url>" \
-e ONCALL_API_TOKEN="<your-oncall-api-token>" \
-e PAGERDUTY_API_TOKEN="<your-pd-api-token>" \
-e PRESERVE_EXISTING_USER_NOTIFICATION_RULES="false" \
oncall-migrator

3. Improved Testing

Added comprehensive test coverage for filtering functionality and updated user notification rule preservation tests

Testing Done

• Manual testing of filtering capabilities in both plan and migrate modes
• Verified notification policy preservation behavior

[joeyorlando]

there was a request to map Amazon CloudWatch Integration in PagerDuty to our Amazon SNS Integration (apparently these are essentially the same thing?)

[vstpme]

LGTM