Verify a DNS Change Across Independent Resolvers Before You Celebrate

id: dns-propagation-verifier
namespace: company.team
description: |
  After a DNS change, poll the changed record across independent public
  resolvers until every one answers with your expected value — or tell
  you exactly which resolvers are still stale when the timeout expires.

triggers:
  - id: propagation_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Call this from the deploy pipeline right after terraform apply or
      the console change, so propagation is verified before the next stage runs.
    key: dns-propagation-check
  - id: drift_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Optional drift watch — re-verify the record every 6 hours to catch
      a change someone made outside your pipeline. Shipped disabled.
    cron: "15 */6 * * *"
    disabled: true

inputs:
  - id: hostname
    type: STRING
    defaults: www.example.com
    description: The record name being verified, e.g. www.example.com or api.example.com.
  - id: record_type
    type: STRING
    defaults: A
    description: DNS record type to query (A, AAAA, CNAME, TXT, ...).
  - id: expected_value
    type: STRING
    defaults: 203.0.113.10
    description: The value every resolver should return once the change has fully
      propagated — the target IP, CNAME, or TXT content.
  - id: resolvers
    type: STRING
    defaults: 8.8.8.8,1.1.1.1,9.9.9.9,208.67.222.222
    description: Comma-separated DNS resolvers to interrogate independently (Google,
      Cloudflare, Quad9, OpenDNS by default).
  - id: timeout_seconds
    type: INT
    defaults: 120
    description: Give up after this many seconds of polling and report which
      resolvers were still stale.
  - id: poll_interval
    type: INT
    defaults: 10
    description: Seconds to wait between rounds of resolver queries.

tasks:
  - id: check_propagation
    type: io.kestra.plugin.scripts.shell.Commands
    description: Install dig in a throwaway Alpine container, then poll every listed
      resolver on an interval until all of them return expected_value or the
      deadline passes. An answer matches when expected_value appears on any line
      of the response, so round-robin pools where your target shares the record
      with other IPs are handled correctly. Each round logs the match count, and
      the task publishes all_matched, matched, resolvers, attempts, and the
      stale list through Kestra's stdout outputs protocol. An empty resolver
      list fails fast instead of reporting a vacuous success.
    containerImage: alpine:3.20
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    commands:
      - |
        set -eu
        apk add --no-cache bind-tools >/dev/null 2>&1
        NAME="{{ inputs.hostname }}"
        TYPE="{{ inputs.record_type }}"
        EXPECTED="{{ inputs.expected_value }}"
        RESOLVERS="{{ inputs.resolvers }}"
        DEADLINE=$(( $(date +%s) + {{ inputs.timeout_seconds }} ))
        attempt=0
        while :; do
          attempt=$(( attempt + 1 ))
          matched=0
          total=0
          pending=""
          OLDIFS=$IFS
          IFS=','
          for r in $RESOLVERS; do
            r=$(printf '%s' "$r" | tr -d ' ')
            if [ -z "$r" ]; then
              continue
            fi
            total=$(( total + 1 ))
            ans=$(dig +short +time=3 +tries=1 "@$r" "$NAME" "$TYPE" 2>/dev/null | tr -d '"' | tr -d '\r')
            if printf '%s\n' "$ans" | grep -qxF "$EXPECTED"; then
              matched=$(( matched + 1 ))
            else
              flat=$(printf '%s' "$ans" | tr '\n' ',')
              pending="${pending}${r}=${flat:-empty}|"
            fi
          done
          IFS=$OLDIFS
          if [ "$total" -eq 0 ]; then
            echo "no resolvers configured — refusing to report success" >&2
            exit 1
          fi
          echo "attempt $attempt: $matched/$total resolvers answer $EXPECTED"
          if [ "$matched" -eq "$total" ]; then
            printf '::{"outputs":{"all_matched":true,"matched":%d,"resolvers":%d,"attempts":%d,"pending":""}}::\n' "$matched" "$total" "$attempt"
            exit 0
          fi
          if [ "$(date +%s)" -ge "$DEADLINE" ]; then
            clean=$(printf '%s' "$pending" | tr -cd 'a-zA-Z0-9.:|=,-')
            printf '::{"outputs":{"all_matched":false,"matched":%d,"resolvers":%d,"attempts":%d,"pending":"%s"}}::\n' "$matched" "$total" "$attempt" "$clean"
            exit 0
          fi
          sleep {{ inputs.poll_interval }}
        done

  - id: check_result
    type: io.kestra.plugin.core.flow.If
    description: Split on the verdict — a fully propagated record is a quiet success
      worth logging with the attempt count; a stale tail is worth waking someone
      with the exact resolver/value pairs that disagree.
    condition: "{{ outputs.check_propagation.vars.all_matched == false }}"
    then:
      - id: alert_stale_resolvers
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Name the resolvers still returning the old answer and their values,
          so the operator knows propagation is genuinely incomplete rather than
          the check being wrong.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "DNS propagation TIMEOUT: {{ inputs.hostname }} {{ inputs.record_type }}={{ inputs.expected_value }} seen by {{ outputs.check_propagation.vars.matched }}/{{ outputs.check_propagation.vars.resolvers }} resolver(s) after {{ inputs.timeout_seconds }}s ({{ outputs.check_propagation.vars.attempts }} rounds). Still stale: {{ outputs.check_propagation.vars.pending }}. Execution {{ execution.id }}."
          }
    else:
      - id: log_propagated
        type: io.kestra.plugin.core.log.Log
        description: Record the round count and resolver count so propagation speed
          becomes visible in the execution history.
        message: "DNS propagated: {{ inputs.hostname }} {{ inputs.record_type }}={{
          inputs.expected_value }} confirmed by all {{
          outputs.check_propagation.vars.resolvers }} resolver(s) in {{
          outputs.check_propagation.vars.attempts }} round(s)."

errors:
  - id: alert_check_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert when the check itself could not run — no dig, no network, bad
      inputs — because a verifier that crashes must never be mistaken for a
      verdict.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "DNS propagation check FAILED in flow {{ flow.id }} (execution {{ execution.id }}) for {{ inputs.hostname }}. No verdict was produced — verify the task container can reach the resolvers on UDP/53 and that the inputs are valid."
      }

outputs:
  - id: propagation_summary
    type: JSON
    description: 'The verdict — e.g. {"all_matched": true, "matched": 4,
      "resolvers": 4, "attempts": 1, "pending": ""} — ready for the deploy
      pipeline or a dashboard.'
    value: "{{ outputs.check_propagation.vars | toJson }}"