Ephemeral DigitalOcean Droplet Runner with Guaranteed Teardown

id: digitalocean-ephemeral-droplet-runner
namespace: company.team
description: |
  Provision a throwaway DigitalOcean droplet for a batch workload, wait
  until it boots, lock it down with a dedicated firewall, run the job, and
  destroy both the firewall and the droplet in a finally block so a failed
  run never leaves a forgotten VM billing by the hour.

inputs:
  - id: region
    type: STRING
    defaults: nyc3
    description: DigitalOcean region slug to provision the droplet in, e.g. nyc3,
      ams3, sgp1.

  - id: droplet_size
    type: STRING
    defaults: s-2vcpu-4gb
    description: Droplet size slug controlling CPU and memory for this run.

  - id: image
    type: STRING
    defaults: ubuntu-24-04-x64
    description: Image slug the droplet boots from.

  - id: admin_cidr
    type: STRING
    defaults: 203.0.113.0/24
    description: CIDR range allowed to reach the droplet over SSH while it exists.

tasks:
  - id: create_droplet
    type: io.kestra.plugin.digitalocean.droplet.Create
    apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"
    description: Provision the ephemeral droplet, tagged so any leftovers are easy
      to spot, with the batch workload injected through cloud-init.
    name: "kestra-runner-{{ execution.id | lower }}"
    region: "{{ inputs.region }}"
    size: "{{ inputs.droplet_size }}"
    image: "{{ inputs.image }}"
    tags:
      - kestra
      - ephemeral
    userData: |
      #cloud-config
      runcmd:
        - echo "replace this with your batch job, e.g. docker run my-etl:latest" >> /var/log/kestra-runner.log

  - id: wait_until_active
    type: io.kestra.plugin.core.flow.LoopUntil
    description: Poll the droplet every 10 seconds until DigitalOcean reports it
      active, failing the run if that takes longer than 10 minutes.
    condition: "{{ outputs.poll_droplet.status == 'active' }}"
    checkFrequency:
      interval: PT10S
      maxDuration: PT10M
    failOnMaxReached: true
    tasks:
      - id: poll_droplet
        type: io.kestra.plugin.digitalocean.droplet.Get
        apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"
        dropletId: "{{ outputs.create_droplet.id }}"

  - id: lock_down
    type: io.kestra.plugin.digitalocean.firewall.Create
    apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"
    description: Attach a single-purpose firewall so the runner only accepts SSH
      from the admin network, while keeping outbound open for package installs
      and data pushes.
    name: "kestra-runner-{{ execution.id | lower }}"
    inboundRules:
      - protocol: tcp
        ports: "22"
        sources:
          addresses:
            - "{{ inputs.admin_cidr }}"
    outboundRules:
      - protocol: tcp
        ports: "1-65535"
        destinations:
          addresses:
            - 0.0.0.0/0
            - ::/0
      - protocol: udp
        ports: "1-65535"
        destinations:
          addresses:
            - 0.0.0.0/0
            - ::/0
    dropletIds:
      - "{{ outputs.create_droplet.id }}"

  - id: run_workload
    type: io.kestra.plugin.core.log.Log
    description: Placeholder for the actual work. The cloud-init script is already
      running on the droplet; replace this task with
      io.kestra.plugin.fs.ssh.Command to drive the machine interactively.
    message: "Droplet {{ outputs.poll_droplet.name }} is active at {{
      outputs.poll_droplet.ip ?? 'IP pending' }} in {{
      outputs.poll_droplet.region }}, workload started via cloud-init"

finally:
  - id: remove_firewall
    type: io.kestra.plugin.core.flow.If
    description: Delete the per-run firewall whenever one was created, even if a
      later task failed.
    condition: "{{ (outputs.lock_down.id ?? '') != '' }}"
    then:
      - id: delete_firewall
        type: io.kestra.plugin.digitalocean.firewall.Delete
        apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"
        firewallId: "{{ outputs.lock_down.id }}"

  - id: remove_droplet
    type: io.kestra.plugin.core.flow.If
    description: Destroy the droplet whenever one was created, so no run ever leaks
      a paid VM.
    condition: "{{ (outputs.create_droplet.id ?? '') != '' }}"
    then:
      - id: delete_droplet
        type: io.kestra.plugin.digitalocean.droplet.Delete
        apiToken: "{{ secret('DIGITALOCEAN_TOKEN') }}"
        dropletId: "{{ outputs.create_droplet.id }}"

errors:
  - id: alert_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Tell the team a run failed. The finally block has already destroyed
      the droplet and firewall.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Ephemeral droplet run failed in flow {{ flow.id }} (execution {{ execution.id }}). Teardown ran in the finally block; verify in the DigitalOcean console that nothing tagged 'ephemeral' remains."
      }