DigitalOcean Account Balance Depletion Sentinel with Kestra

id: digitalocean-account-balance-depletion-sentinel
namespace: company.team

description: |
  Read a DigitalOcean account's real balance, classify it HEALTHY, WARNING, CRITICAL or
  PROBE_FAILED from the real remaining credit or amount owed, and alert Slack with the exact
  dollar figures before services get suspended for non-payment, never an invented number.

inputs:
  - id: low_credit_warning_threshold_usd
    type: INT
    displayName: Low credit warning threshold (USD)
    description: When accountBalance is still negative (credit remaining), alert
      WARNING once that remaining credit drops below this many dollars.
    defaults: 10

tasks:
  - id: probe_balance
    type: io.kestra.plugin.digitalocean.billing.GetBalance
    description: Reads the account's real accountBalance (negative means credit
      remaining, zero or positive means money owed), monthToDateUsage, and
      monthToDateBalance.
    allowFailure: true
    apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"

  - id: classify_balance_status
    type: io.kestra.plugin.core.debug.Return
    description: PROBE_FAILED when the probe did not return at all, CRITICAL when
      accountBalance is at or above zero (credit exhausted, money now owed),
      WARNING when remaining credit is below low_credit_warning_threshold_usd,
      HEALTHY otherwise.
    format: "{{ outputs.probe_balance is not defined ? 'PROBE_FAILED' : (
      outputs.probe_balance.accountBalance >= 0 ? 'CRITICAL' : (
      (outputs.probe_balance.accountBalance * -1) <
      inputs.low_credit_warning_threshold_usd ? 'WARNING' : 'HEALTHY' ) ) }}"

  - id: route_by_balance_status
    type: io.kestra.plugin.core.flow.Switch
    description: Branch A logs an account with healthy remaining credit. Branch B
      alerts Slack with the real accountBalance and monthToDateUsage figures,
      never an invented number.
    value: "{{ outputs.classify_balance_status.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "DigitalOcean account healthy. accountBalance={{
            outputs.probe_balance.accountBalance }} USD, monthToDateUsage={{
            outputs.probe_balance.monthToDateUsage }} USD."
      "WARNING":
        - id: alert_warning
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "DigitalOcean account balance WARNING. Remaining credit: " ~ (outputs.probe_balance.accountBalance * -1) ~ " USD, below the " ~ inputs.low_credit_warning_threshold_usd ~ " USD threshold. Month-to-date usage: " ~ outputs.probe_balance.monthToDateUsage ~ " USD."} | toJson }}
      "CRITICAL":
        - id: alert_critical
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "DigitalOcean account balance CRITICAL. accountBalance=" ~ outputs.probe_balance.accountBalance ~ " USD, credit is exhausted and the account now owes money. Services may be suspended for non-payment. Month-to-date usage: " ~ outputs.probe_balance.monthToDateUsage ~ " USD."} | toJson }}
      "PROBE_FAILED":
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "DigitalOcean account balance probe did not return a result. Check the DIGITALOCEAN_TOKEN secret."} | toJson }}
    defaults:
      - id: log_unexpected_status
        type: io.kestra.plugin.core.log.Log
        message: "Unexpected classify_balance_status value: {{
          outputs.classify_balance_status.value }}"

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: Final audit log confirming the gate ran, regardless of the branch
      taken above.
    message: "DigitalOcean account balance depletion sentinel completed. status={{
      outputs.classify_balance_status.value }}"

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {"text": "DigitalOcean account balance depletion sentinel flow failed (execution " ~ execution.id ~ "). Check the execution logs."} | toJson }}

triggers:
  - id: every_morning
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled.
    cron: "0 7 * * *"
    disabled: true
    inputs:
      low_credit_warning_threshold_usd: 10

A DigitalOcean account running on promotional or prepaid credit shows no warning as that credit runs down, the droplets, databases, and load balancers it pays for keep running right up until the balance crosses zero, at which point the account owes money and risks suspension for non-payment with no notice beyond an email easy to miss. This blueprint reads the account's real balance on a schedule and alerts Slack with the exact remaining credit or amount owed, never an invented figure.

How it works

probe_balance (io.kestra.plugin.digitalocean.billing.GetBalance) reads accountBalance (negative means credit remaining, zero or positive means money owed), monthToDateUsage, and monthToDateBalance, with allowFailure: true so a bad or expired API token does not stop the flow before it can be classified as PROBE_FAILED below.
classify_balance_status (io.kestra.plugin.core.debug.Return) returns PROBE_FAILED when the probe did not return at all, CRITICAL when accountBalance is at or above zero, WARNING when the real remaining credit is below low_credit_warning_threshold_usd, HEALTHY otherwise.
route_by_balance_status (io.kestra.plugin.core.flow.Switch) branches on that status: HEALTHY logs it, the other three alert Slack with the real dollar figures, never an invented number. A defaults branch logs anything unexpected.
log_audit_summary always runs last. The errors block posts to Slack if the flow itself fails outside the gate logic above.

What you get

A real read of the account's own balance, not a guess from when the last invoice email arrived.
A Slack alert naming the real remaining credit or the real amount owed, never an invented number.
A warning before the balance crosses zero, not only after services are already at risk of suspension.

Who it's for

Platform and FinOps teams running infrastructure on DigitalOcean on prepaid or promotional credit who need to know before that credit runs out, not after.
Teams evaluating the DigitalOcean plugin who want a working example of billing.GetBalance and its signed-balance convention.

Why orchestrate this with Kestra

DigitalOcean's own notifications for a depleted balance arrive by email, easy to miss in a shared inbox, and carry no severity tiering of their own. Kestra adds the schedule, a warning tier before the balance actually crosses zero, and a Slack alert with the real figures as one declarative, auditable flow.

Prerequisites

A DigitalOcean account and a personal access token with read access to billing, generated under API in the DigitalOcean control panel. DigitalOcean's billing API has no local emulator, this gate runs against a real account; a free-tier account and token are sufficient to call this endpoint.
A Slack incoming webhook for alerts.

Secrets

DIGITALOCEAN_TOKEN: personal access token used by the probe task.
SLACK_WEBHOOK: Slack incoming webhook URL used by the alert tasks and the errors block.

In Kestra OSS, set these as base64-encoded environment variables, for example SECRET_DIGITALOCEAN_TOKEN, SECRET_SLACK_WEBHOOK.

Quick start

Generate a DigitalOcean API token and add the two secrets above.
Run this flow manually with the defaults, it should report HEALTHY on an account with more than the threshold in remaining credit, or CRITICAL if the account already owes money.
Lower low_credit_warning_threshold_usd above the account's current remaining credit, run again, it should report WARNING naming the real figure.
Enable the every_morning trigger.

How to extend

Add ListBillingHistory to break the alert down by which resource type drove the month-to-date usage, not only the total.
Add a remediation branch that powers off a named, non-critical droplet via droplet.Action when CRITICAL, gated behind an explicit operator-supplied droplet ID, never an automatic bulk shutdown.
Track generatedAt across runs to alert if the figures themselves have gone stale, meaning the account's billing data is not refreshing as expected.

Pitfalls

accountBalance's sign convention is easy to get backwards, negative means credit remaining, zero or positive means money owed, this gate's classification depends on that being read correctly.
This gate only reads and alerts, it never pauses or deletes any resource automatically, choosing what to shut down to control cost needs a human decision, not an automated guess.
monthToDateUsage resets each billing period, a WARNING or CRITICAL reading near the start of a new period reflects the account's actual remaining credit, not a bug in this gate.

DigitalOcean Account Balance Depletion Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

DigitalOcean Account Balance Depletion Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Enforce CI/CD guardrails with OPA (Rego) policy gate

Okta SAML SSO App Certificate and Configuration Health Probe

Ingest PLC Telemetry Only When Every Reading Is Trustworthy

Gate OIDC Signing-Key Rollovers with a Pinned JWKS

Run a task on an on-demand Databricks cluster

Okta System Log Suspicious IP Session Hijack Sentinel

More Cloud Blueprints

Business-Hours Resize for DigitalOcean Managed Databases

DigitalOcean New Droplet Governance Guard

DigitalOcean Alert Policy Compliance Gate

Dex IdP SAML Connector Authentication Error Sentinel

Dex LDAP User Bind Timeout Sentinel

Nightly DigitalOcean Droplet Snapshot Backups by Tag

New to Kestra?