Detect Public IP Changes with the KV Store

id: public-ip-change-detector
namespace: company.team
description: |
  Fetch the public IP your Kestra worker egresses from, compare it with the last
  saved value, and log and remember it whenever it changes.

triggers:
  - id: every_15_minutes
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the egress IP every 15 minutes; shipped disabled so it does
      not run until you enable it.
    cron: "*/15 * * * *"
    disabled: true
  - id: manual_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Call on demand, for example after a VPN or NAT gateway change, to
      re-check right away.
    key: public-ip-check

inputs:
  - id: ip_service_url
    type: URI
    defaults: https://api.ipify.org?format=json
    description: Endpoint that returns the caller's public IP as JSON like
      {"ip":"203.0.113.7"}.
  - id: kv_key
    type: STRING
    defaults: public_ip_last
    description: Key in the Kestra KV store where the last seen IP is saved.

tasks:
  - id: fetch_ip
    type: io.kestra.plugin.core.http.Request
    description: Ask the IP service which address this worker's traffic comes from.
    uri: "{{ inputs.ip_service_url }}"
    method: GET

  - id: read_last_ip
    type: io.kestra.plugin.core.kv.Get
    description: Load the IP saved by the previous run. Missing on the very first
      run, which is fine.
    key: "{{ inputs.kv_key }}"
    errorOnMissing: false

  - id: compare_ip
    type: io.kestra.plugin.scripts.shell.Commands
    description: Validate the response looks like an IP address, then classify the
      run as first_run, unchanged or changed and emit it through the stdout
      outputs protocol. A malformed response fails the task instead of being
      saved as an IP.
    taskRunner:
      type: io.kestra.plugin.core.runner.Process
    env:
      CURRENT_IP: "{{ fromJson(outputs.fetch_ip.body).ip }}"
      PREVIOUS_IP: "{{ outputs.read_last_ip.value ?? '' }}"
    commands:
      - |
        set -eu
        if ! echo "$CURRENT_IP" | grep -Eq '^([0-9]{1,3}\.){3}[0-9]{1,3}$|^[0-9a-fA-F:]+:[0-9a-fA-F:]*$'; then
          echo "Unexpected response from the IP service: '$CURRENT_IP'" >&2
          exit 1
        fi
        if [ -z "$PREVIOUS_IP" ]; then status=first_run
        elif [ "$PREVIOUS_IP" = "$CURRENT_IP" ]; then status=unchanged
        else status=changed
        fi
        echo "current=$CURRENT_IP previous=${PREVIOUS_IP:-none} status=$status"
        echo "::{\"outputs\":{\"status\":\"$status\"}}::"

  - id: handle_result
    type: io.kestra.plugin.core.flow.If
    description: Do something only when the IP is new or changed; otherwise just
      record that nothing moved.
    condition: "{{ outputs.compare_ip.vars.status != 'unchanged' }}"
    then:
      - id: save_ip
        type: io.kestra.plugin.core.kv.Set
        description: Remember the new IP so the next run compares against it.
        key: "{{ inputs.kv_key }}"
        value: "{{ fromJson(outputs.fetch_ip.body).ip }}"

      - id: log_change
        type: io.kestra.plugin.core.log.Log
        level: WARN
        description: Surface the change at WARN level. Replace with a Slack, email or
          ticket task to notify your team.
        message: "Public IP {{ outputs.compare_ip.vars.status }}: {{
          outputs.read_last_ip.value ?? 'none' }} -> {{
          fromJson(outputs.fetch_ip.body).ip }}. Allow-lists that reference the
          old address may need updating."
    else:
      - id: log_unchanged
        type: io.kestra.plugin.core.log.Log
        description: Leave a trail so the execution history shows the check ran and the
          IP held steady.
        message: "Public IP unchanged: {{ fromJson(outputs.fetch_ip.body).ip }}."

outputs:
  - id: current_ip
    type: STRING
    description: The public IP seen by this run.
    value: "{{ fromJson(outputs.fetch_ip.body).ip }}"
  - id: status
    type: STRING
    description: first_run, unchanged or changed.
    value: "{{ outputs.compare_ip.vars.status }}"