Feature-Flag Progressive Delivery with an Error-Rate Guard

id: feature-flag-progressive-delivery-slo-gate
namespace: company.team
description: |
  Ramp a feature flag through staged percentages with an SLO guard at every step:
  each stage sets the flag, waits for real traffic, queries Prometheus, and the
  moment the error rate breaches, the flag is disabled and an issue is filed.

inputs:
  - id: flag_api_url
    type: STRING
    displayName: Flag provider API endpoint
    description: Full URL for the JSON PATCH that changes the rollout
      (LaunchDarkly-style shown; adapt to Unleash/OpenFeature).
    defaults: https://api.launchdarkly.ai/api/v2/flags/my-project/new-checkout

  - id: flag_key
    type: STRING
    displayName: Flag key
    description: Key of the flag being ramped - also the metric label used in PromQL.
    defaults: new-checkout

  - id: flag_environment
    type: STRING
    displayName: Flag environment
    defaults: production

  - id: ramp_percentages
    type: JSON
    displayName: Rollout stages (%)
    description: Percentages to ramp through, one guard cycle per stage.
    defaults:
      - 10
      - 25
      - 50
      - 100

  - id: observation_minutes
    type: INT
    displayName: Observation window per stage (minutes)
    defaults: 10

  - id: max_error_rate
    type: FLOAT
    displayName: Maximum 5xx error rate
    description: Breach threshold checked after every stage - 0.01 means one percent.
    defaults: 0.01

  - id: repository
    type: STRING
    displayName: GitHub repository for abort issues
    defaults: your-org/your-repo

tasks:
  - id: ramp_stages
    type: io.kestra.plugin.core.flow.Loop
    description: One guard cycle per percentage - set the flag, observe real
      traffic, verify against the error-rate budget.
    values: "{{ inputs.ramp_percentages }}"
    tasks:
      - id: set_stage
        type: io.kestra.plugin.core.http.Request
        description: PATCH the flag provider to this stage's percentage (LaunchDarkly
          JSON-patch shape).
        uri: "{{ inputs.flag_api_url }}"
        method: PATCH
        contentType: application/json
        headers:
          Authorization: "Bearer {{ secret('FLAG_API_TOKEN') }}"
        body: |
          [
            {"op": "replace", "path": "/environments/{{ inputs.flag_environment }}/on", "value": true},
            {"op": "replace", "path": "/environments/{{ inputs.flag_environment }}/targets", "value": [{"percentage": {{ item.value }}, "values": ["all"]}]}
          ]

      - id: observe_stage
        type: io.kestra.plugin.core.flow.Sleep
        description: Let the stage accumulate real user traffic before judging it.
        duration: "PT{{ inputs.observation_minutes }}M"

      - id: error_rate_check
        type: io.kestra.plugin.prometheus.Query
        description: 5xx ratio for the flagged traffic over the last five minutes as a
          single scalar.
        url: "{{ secret('PROMETHEUS_URL') }}"
        query: 'sum(rate(http_requests_total{flag="{{ trigger.body.key ??
          inputs.flag_key }}", status=~"5.."}[5m])) /
          sum(rate(http_requests_total{flag="{{ trigger.body.key ??
          inputs.flag_key }}"}[5m]))'
        fetchType: FETCH_ONE

      - id: guard
        type: io.kestra.plugin.core.flow.If
        description: Breach at any stage disables the flag immediately, files an issue,
          and stops the ramp.
        condition: "{{ outputs.error_rate_check.metric.value | number >
          inputs.max_error_rate }}"
        then:
          - id: disable_flag
            type: io.kestra.plugin.core.http.Request
            description: Turn the flag off and zero the rollout - users leave through the
              safe path instantly.
            uri: "{{ inputs.flag_api_url }}"
            method: PATCH
            contentType: application/json
            headers:
              Authorization: "Bearer {{ secret('FLAG_API_TOKEN') }}"
            body: |
              [
                {"op": "replace", "path": "/environments/{{ inputs.flag_environment }}/on", "value": false},
                {"op": "replace", "path": "/environments/{{ inputs.flag_environment }}/targets", "value": [{"percentage": 0, "values": ["all"]}]}
              ]

          - id: open_issue
            type: io.kestra.plugin.github.issues.Create
            description: Assignable ticket for the team owning the flag, with the stage and
              measured rate.
            jwtToken: "{{ secret('GITHUB_TOKEN') }}"
            repository: "{{ inputs.repository }}"
            title: "Flag ramp aborted: {{ trigger.body.key ?? inputs.flag_key }} at {{
              item.value }}% (error rate {{
              outputs.error_rate_check.metric.value }})"
            labels:
              - progressive-delivery
              - rollback
            body: |
              ## Feature-flag ramp aborted

              | Field | Value |
              |---|---|
              | Flag | {{ trigger.body.key ?? inputs.flag_key }} |
              | Stage | {{ item.value }}% |
              | Error rate | {{ outputs.error_rate_check.metric.value }} |
              | Threshold | {{ inputs.max_error_rate }} |
              | Environment | {{ inputs.flag_environment }} |

              The flag was disabled automatically by execution `{{ execution.id }}` after {{ inputs.observation_minutes }} minutes of observation. Diagnose before re-enabling and re-running the ramp.

          - id: alert_slack
            type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
            url: "{{ secret('SLACK_WEBHOOK_URL') }}"
            messageText: |
              :no_entry: Flag ramp aborted for *{{ trigger.body.key ?? inputs.flag_key }}* at {{ item.value }}% - error rate {{ outputs.error_rate_check.metric.value }} exceeds {{ inputs.max_error_rate }}. Flag disabled, issue filed, execution stopping.

          - id: fail_ramp
            type: io.kestra.plugin.core.execution.Fail
            description: Fail so any release pipeline waiting on this ramp halts instead of
              continuing blind.
            errorMessage: "Flag {{ trigger.body.key ?? inputs.flag_key }} aborted at {{
              item.value }}%: error rate {{
              outputs.error_rate_check.metric.value }} > {{
              inputs.max_error_rate }} - flag disabled."

  - id: announce_full_rollout
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Every stage held - the flag is fully rolled out with the guard
      history attached.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    messageText: |
      :white_check_mark: Flag *{{ trigger.body.key ?? inputs.flag_key }}* ramped through {{ inputs.ramp_percentages | json }} without breaching {{ inputs.max_error_rate }}. Full rollout complete (execution {{ execution.id }}).

outputs:
  - id: flag
    type: STRING
    value: "{{ trigger.body.key ?? inputs.flag_key }}"

  - id: stages_planned
    type: INT
    value: "{{ inputs.ramp_percentages | length }}"

  - id: ramp
    type: JSON
    value: "{{ inputs.ramp_percentages | json }}"

errors:
  - id: alert_on_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    messageText: ":rotating_light: Flag ramp {{ flow.id }} FAILED (execution {{
      execution.id }}): {{ error.message }}"

triggers:
  - id: flag_change
    type: io.kestra.plugin.core.trigger.Webhook
    description: Fire this from your flag provider's webhook (LaunchDarkly/Unleash
      flag-change event) or manually. The payload key overrides the flag key.
      Replace with your own value.
    key: replace-with-a-random-key