Fastly Month-to-Date Cost Guard

id: fastly-cost-guard
namespace: company.team
description: |
  Catch a CDN bill surprise while the month is still running. The flow
  pulls Fastly's month-to-date usage plus a per-service breakdown, computes
  total bandwidth in GB with a small Python step, and alerts Slack when the
  number crosses a threshold.

inputs:
  - id: bandwidth_threshold_gb
    type: FLOAT
    defaults: 5000
    description: Month-to-date bandwidth in GB above which the flow raises a cost alert.

tasks:
  - id: month_to_date
    type: io.kestra.plugin.fastly.stats.MonthToDateUsage
    description: Pull the account's month-to-date usage rollup from Fastly, the same
      numbers the invoice will be built from.
    apiToken: "{{ secret('FASTLY_API_TOKEN') }}"

  - id: usage_by_service
    type: io.kestra.plugin.fastly.stats.Usage
    description: Pull the same period broken down per service, so when the total is
      high the execution already holds the answer to which service is driving
      it.
    apiToken: "{{ secret('FASTLY_API_TOKEN') }}"
    from: "{{ execution.startDate | date('yyyy-MM') }}-01"
    to: "{{ execution.startDate | date('yyyy-MM-dd') }}"
    byService: true

  - id: compute_bandwidth
    type: io.kestra.plugin.scripts.python.Script
    description: Sum every bandwidth figure in the month-to-date payload and emit a
      single GB scalar through the outputs protocol, so the threshold check
      compares one number.
    taskRunner:
      type: io.kestra.plugin.core.runner.Process
    env:
      MTD_DATA: "{{ outputs.month_to_date.data | toJson }}"
    script: |
      import json
      import os

      def walk(node, acc):
          if isinstance(node, dict):
              for key, value in node.items():
                  if key == "bandwidth" and isinstance(value, (int, float)):
                      acc.append(value)
                  else:
                      walk(value, acc)
          elif isinstance(node, list):
              for item in node:
                  walk(item, acc)

      data = json.loads(os.environ["MTD_DATA"])
      values = []
      walk(data, values)
      bandwidth_gb = round(sum(values) / (1024 ** 3), 2)

      print(f"Month-to-date bandwidth: {bandwidth_gb} GB across {len(values)} bandwidth entries")
      print("::" + json.dumps({"outputs": {"bandwidth_gb": bandwidth_gb}}) + "::")

  - id: check_threshold
    type: io.kestra.plugin.core.flow.If
    description: Compare the computed GB scalar against the threshold input and only
      alert when the month is tracking over.
    condition: "{{ outputs.compute_bandwidth.vars.bandwidth_gb >
      inputs.bandwidth_threshold_gb }}"
    then:
      - id: alert_overage
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Warn the channel mid-month with the measured number and the
          threshold, while there is still time to react before the invoice.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "Fastly cost guard: month-to-date bandwidth is {{ outputs.compute_bandwidth.vars.bandwidth_gb }} GB, above the {{ inputs.bandwidth_threshold_gb }} GB threshold. The per-service breakdown is attached to execution {{ execution.id }}, check which service is driving it."
          }
    else:
      - id: log_ok
        type: io.kestra.plugin.core.log.Log
        description: Keep a quiet record of healthy checks, so the guard's history shows
          the month's trajectory.
        message: "Fastly month-to-date bandwidth is {{
          outputs.compute_bandwidth.vars.bandwidth_gb }} GB, under the {{
          inputs.bandwidth_threshold_gb }} GB threshold."

errors:
  - id: alert_failure
    type: io.kestra.plugin.discord.DiscordIncomingWebhook
    description: Alert when the guard itself fails, since a broken cost check feels
      exactly like a healthy month until the invoice arrives.
    url: "{{ secret('DISCORD_WEBHOOK_URL') }}"
    payload: |
      {
        "content": "Fastly cost guard FAILED in flow {{ flow.id }} (execution {{ execution.id }}). Month-to-date usage was NOT checked, rerun it or check the stats API calls in the logs."
      }

triggers:
  - id: weekly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the month-to-date number every Monday morning, several times
      per billing cycle.
    cron: "0 8 * * 1"
    disabled: true