Flagsmith Feature Flag Health and Drift Sentinel

id: flagsmith-feature-flag-health-and-drift-sentinel
namespace: company.platform

description: |
  Continuously monitors Flagsmith feature flagging engine readiness and evaluates critical production feature toggle states, detects configuration drift or missing flags, and dispatches actionable Slack incident alerts to safeguard deployment rollouts.

inputs:
  - id: flagsmith_host
    type: STRING
    displayName: Flagsmith Endpoint Host
    defaults: "http://flagsmith.internal:8000"
    description: "Base HTTP URL of the target Flagsmith server API."

  - id: critical_feature_flag
    type: STRING
    displayName: Critical Feature Flag Name
    defaults: "enable_production_checkout"
    description: "Name of the critical feature flag that must be evaluated for state
      compliance."

  - id: expected_flag_state
    type: BOOL
    displayName: Expected Flag State
    defaults: true
    description: "Expected enabled state (true/false) of the critical feature flag
      in the target environment."

  - id: slack_channel
    type: STRING
    displayName: Operational Slack Channel
    defaults: "#deploy-alerts"
    description: "Target Slack channel or webhook destination for flag drift and
      incident alerts."

triggers:
  - id: scheduled_sentinel_audit
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 */4 * * *"
    disabled: true
    inputs:
      flagsmith_host: "http://flagsmith.internal:8000"
      critical_feature_flag: "enable_production_checkout"
      expected_flag_state: true
      slack_channel: "#deploy-alerts"

tasks:
  - id: probe_engine_health
    type: io.kestra.plugin.core.http.Request
    uri: "{{ inputs.flagsmith_host }}/health"
    method: GET
    headers:
      Accept: application/json
    timeout: PT15S
    description: "Queries the Flagsmith health endpoint to verify API server
      availability and core engine responsiveness."

  - id: probe_environment_flags
    type: io.kestra.plugin.core.http.Request
    uri: "{{ inputs.flagsmith_host }}/api/v1/flags/"
    method: GET
    headers:
      Accept: application/json
      X-Environment-Key: "{{ secret('FLAGSMITH_ENVIRONMENT_KEY') }}"
    timeout: PT30S
    description: "Fetches all feature flag states from the target Flagsmith
      environment using the authenticated environment key."

  - id: evaluate_flag_state_and_health
    type: io.kestra.plugin.core.flow.Switch
    value: >-
      {% set health = outputs.probe_engine_health.body %} {% set health_status =
      health.status | default('ok') %} {% set flags_payload =
      outputs.probe_environment_flags.body %} {% set flags_list =
      flags_payload.flags | default(flags_payload | default([])) %} {% set
      target = inputs.critical_feature_flag | lower %} {% set matched_flag =
      null %} {% if flags_list is iterable %}
        {% for item in flags_list %}
          {% set item_name = item.feature.name | default(item.name | default('')) | lower %}
          {% if item_name == target %}
            {% set matched_flag = item %}
          {% endif %}
        {% endfor %}
      {% endif %} {% if health_status != 'ok' and
      outputs.probe_engine_health.code != 200 %}
        ENGINE_UNHEALTHY
      {% elseif matched_flag is null %}
        FLAG_NOT_FOUND
      {% elseif matched_flag.enabled != inputs.expected_flag_state %}
        FLAG_STATE_DRIFT
      {% else %}
        COMPLIANT
      {% endif %}
    cases:
      COMPLIANT:
        - id: log_compliant_status
          type: io.kestra.plugin.core.log.Log
          message: "Flagsmith engine on '{{ inputs.flagsmith_host }}' is healthy. Critical
            flag '{{ inputs.critical_feature_flag }}' matches expected state ({{
            inputs.expected_flag_state }})."

      FLAG_STATE_DRIFT:
        - id: alert_flag_drift_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "attachments": [
                {
                  "color": "#FFA726",
                  "title": "⚠️ Flagsmith Critical Flag State Drift Detected",
                  "text": "The critical feature flag `{{ inputs.critical_feature_flag }}` has drifted from its expected state on `{{ inputs.flagsmith_host }}`.\n*Expected State:* `{{ inputs.expected_flag_state }}`\n*Action:* Verify whether an unauthorized toggle or emergency rollout override occurred.",
                  "footer": "Kestra Sentinel | Feature Toggle Drift Guard"
                }
              ]
            }

        - id: log_flag_drift
          type: io.kestra.plugin.core.log.Log
          message: "Flag state drift detected for '{{ inputs.critical_feature_flag }}' on
            '{{ inputs.flagsmith_host }}'. Investigation required."

      FLAG_NOT_FOUND:
        - id: alert_missing_flag_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "attachments": [
                {
                  "color": "#E53935",
                  "title": "❌ Flagsmith Critical Flag Missing",
                  "text": "Expected feature flag `{{ inputs.critical_feature_flag }}` was not found in the environment on `{{ inputs.flagsmith_host }}`.\n*Environment Key:* Configured secret\nVerify flag registration in the Flagsmith project dashboard.",
                  "footer": "Kestra Sentinel | Deployment Gate Alert"
                }
              ]
            }

        - id: log_missing_flag
          type: io.kestra.plugin.core.log.Log
          message: "Critical flag '{{ inputs.critical_feature_flag }}' was not returned by
            the Flagsmith environment API."

      ENGINE_UNHEALTHY:
        - id: alert_engine_unhealthy_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "attachments": [
                {
                  "color": "#D32F2F",
                  "title": "🚨 Flagsmith Engine Health Check Failed",
                  "text": "Flagsmith health probe returned non-200 or unhealthy status on `{{ inputs.flagsmith_host }}`.\nFeature flag evaluation may be degraded or offline.",
                  "footer": "Kestra Sentinel | Platform Availability Alert"
                }
              ]
            }

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    message: "Completed Flagsmith audit for flag '{{ inputs.critical_feature_flag
      }}' on {{ inputs.flagsmith_host }} at {{ now() }}. Engine status code: {{
      outputs.probe_engine_health.code }}."

errors:
  - id: alert_probe_failure_slack
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "attachments": [
          {
            "color": "#D32F2F",
            "title": "🚨 Flagsmith Sentinel Probe Failure",
            "text": "The Flagsmith compliance probe encountered an unhandled network error or connection timeout connecting to `{{ inputs.flagsmith_host }}`.\n*Execution ID:* `{{ flow.executionId }}`\n*Error Message:* `{{ flow.errorMessage | default('Unknown execution error') }}`",
            "footer": "Kestra Orchestrator | Automated Incident Management"
          }
        ]
      }