Sweep Ephemeral Test and Preview Namespaces by Pull Request Status and TTL

id: kubernetes-ephemeral-test-namespace-ttl-sweeper
namespace: company.team

description: |
  Discovers and deletes stale Kubernetes preview and ephemeral test namespaces whose
  pull requests have been closed or merged, or whose age exceeds max TTL, reporting
  summary actions to Slack with strict dry-run and blast radius safeguards.

concurrency:
  limit: 1
  behavior: QUEUE

inputs:
  - id: preview_label_selector
    type: STRING
    defaults: "preview=true"
    displayName: Preview Label Selector
    description: "Kubernetes label selector used to discover candidate ephemeral
      namespaces (server-side filter via kubectl -l)."

  - id: name_regex
    type: STRING
    defaults: "^pr-[0-9]+$"
    displayName: Namespace Name Regex
    description: "Regular expression pattern required for a namespace name to be
      considered for deletion."

  - id: github_repo
    type: STRING
    defaults: "kestra-io/blueprints"
    displayName: GitHub Repository
    description: "GitHub repository in owner/repo format whose pull requests
      correspond to ephemeral namespaces."

  - id: max_ttl_hours
    type: INT
    defaults: 72
    displayName: Maximum TTL (Hours)
    description: "Maximum allowable namespace age in hours before sweeping
      regardless of open pull request state."

  - id: min_age_hours
    type: INT
    defaults: 1
    displayName: Minimum Age Grace Period (Hours)
    description: "Minimum age required before a namespace can be swept, protecting
      newly created environments."

  - id: max_deletions_per_run
    type: INT
    defaults: 5
    displayName: Blast Radius Deletion Cap
    description: "Maximum number of namespaces to delete in a single sweep
      execution; remainder are deferred."

  - id: dry_run
    type: BOOL
    defaults: true
    displayName: Dry Run Mode
    description: "When true, discovers and evaluates real cluster state and logs
      planned actions without deleting."

  - id: slack_channel
    type: STRING
    defaults: "#devops-alerts"
    displayName: Slack Notification Channel
    description: "Target Slack channel for the sweep execution report."

triggers:
  - id: sweep_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Runs the namespace sweep periodically every 2 hours."
    cron: "0 */2 * * *"
    disabled: true

tasks:
  - id: list_namespaces
    type: io.kestra.plugin.scripts.shell.Commands
    description: "Lists cluster namespaces matching the preview label selector using
      kubectl (server-side label filter) and writes them to namespaces.json."
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    containerImage: alpine/k8s:1.30.6
    env:
      K8S_MASTER_URL: "{{ secret('K8S_MASTER_URL') }}"
      K8S_TOKEN: "{{ secret('K8S_TOKEN') }}"
      K8S_CA_CERT_DATA: "{{ secret('K8S_CA_CERT_DATA') }}"
      LABEL_SELECTOR: "{{ inputs.preview_label_selector }}"
    outputFiles:
      - namespaces.json
    commands:
      - |
        set -eu
        printf '%s' "$K8S_CA_CERT_DATA" | base64 -d > ca.crt
        kubectl \
          --server="$K8S_MASTER_URL" \
          --token="$K8S_TOKEN" \
          --certificate-authority=ca.crt \
          get namespaces -l "$LABEL_SELECTOR" -o json \
          | jq '[.items[] | {name: .metadata.name, creationTimestamp: .metadata.creationTimestamp, deletionTimestamp: (.metadata.deletionTimestamp // null)}]' \
          > namespaces.json
        echo "Discovered $(jq length namespaces.json) namespace(s) matching '$LABEL_SELECTOR'"

  - id: filter_candidates
    type: io.kestra.plugin.core.output.OutputValues
    description: "Filters discovered namespaces by name regex, exclusion list,
      terminating phase, and minimum age grace period."
    values:
      candidates: >-
        {{
          fromJson(read(outputs.list_namespaces.outputFiles['namespaces.json'])) | jq(
            'map(select(' ~
              '(.name | test("' ~ inputs.name_regex ~ '")) and ' ~
              '(.name != "kube-system" and .name != "kube-public" and .name != "kube-node-lease" and .name != "default") and ' ~
              '(.deletionTimestamp == null or .deletionTimestamp == "") and ' ~
              '((now - (.creationTimestamp | fromdateiso8601)) >= (' ~ (inputs.min_age_hours * 3600) ~ '))' ~
            ')) | sort_by(.creationTimestamp | fromdateiso8601) | map({' ~
              'name: .name, ' ~
              'creationTimestamp: .creationTimestamp, ' ~
              'age_hours: (((now - (.creationTimestamp | fromdateiso8601)) / 3600) | floor), ' ~
              'pr_number: (if (.name | test("[0-9]+")) then (.name | capture("(?<pr>[0-9]+)") | .pr) else "" end)' ~
            '})'
          ) | first ?? []
        }}

  - id: evaluate_candidates_loop
    type: io.kestra.plugin.core.flow.Loop
    description: "Iterates sequentially through candidate namespaces to query GitHub
      pull request states and calculate verdicts."
    values: "{{ outputs.filter_candidates.values.candidates }}"
    concurrencyLimit: 1
    outputs:
      - id: verdict
        type: JSON
        value: "{{ outputs.record_verdict.values.verdict }}"
    tasks:
      - id: check_github_pr
        type: io.kestra.plugin.core.flow.If
        description: "Queries GitHub Pull Request API when the candidate namespace name
          contains a pull request number."
        condition: "{{ item.value.pr_number != '' }}"
        then:
          - id: get_pr
            type: io.kestra.plugin.core.http.Request
            description: "Fetches pull request details from the GitHub REST API."
            uri: "https://api.github.com/repos/{{ inputs.github_repo }}/pulls/{{
              item.value.pr_number }}"
            method: GET
            headers:
              Accept: "application/vnd.github+json"
              Authorization: "Bearer {{ secret('GITHUB_TOKEN') }}"
              X-GitHub-Api-Version: "2022-11-28"
            options:
              allowFailed: true
            retry:
              type: constant
              interval: PT5S
              maxAttempts: 3

      - id: record_verdict
        type: io.kestra.plugin.core.output.OutputValues
        description: "Evaluates qualification status, reason, and any API errors for
          this candidate namespace."
        values:
          verdict: >-
            {{
              {
                "name": item.value.name,
                "age_hours": item.value.age_hours,
                "pr_number": (item.value.pr_number != "" ? item.value.pr_number : null),
                "pr_state": (
                  item.value.pr_number != "" and outputs.get_pr is defined ? (
                    outputs.get_pr.code == 200 ? (outputs.get_pr.body | jq('.state') | first) :
                    outputs.get_pr.code == 404 ? "not_found" : "error"
                  ) : "none"
                ),
                "qualifies": (
                  item.value.pr_number != "" and outputs.get_pr is defined ? (
                    outputs.get_pr.code == 200 ? (
                      ((outputs.get_pr.body | jq('.merged') | first) == true) or
                      ((outputs.get_pr.body | jq('.state') | first) == "closed") or
                      (item.value.age_hours > inputs.max_ttl_hours)
                    ) :
                    outputs.get_pr.code == 404 ? (item.value.age_hours > inputs.max_ttl_hours) :
                    false
                  ) :
                  (item.value.age_hours > inputs.max_ttl_hours)
                ),
                "reason": (
                  item.value.pr_number != "" and outputs.get_pr is defined ? (
                    outputs.get_pr.code == 200 ? (
                      ((outputs.get_pr.body | jq('.merged') | first) == true) ? "pr_merged" :
                      ((outputs.get_pr.body | jq('.state') | first) == "closed") ? "pr_closed" :
                      (item.value.age_hours > inputs.max_ttl_hours) ? "ttl_exceeded" : "active_pr_within_ttl"
                    ) :
                    outputs.get_pr.code == 404 ? (
                      (item.value.age_hours > inputs.max_ttl_hours) ? "ttl_exceeded" : "pr_not_found_within_ttl"
                    ) :
                    "github_api_error"
                  ) :
                  (
                    (item.value.age_hours > inputs.max_ttl_hours) ? "ttl_exceeded" : "within_ttl"
                  )
                ),
                "error": (
                  item.value.pr_number != "" and outputs.get_pr is defined and outputs.get_pr.code != 200 and outputs.get_pr.code != 404 ?
                  ("GitHub API returned HTTP " ~ outputs.get_pr.code ~ " for PR #" ~ item.value.pr_number) :
                  null
                )
              } | toJson
            }}

  - id: plan_actions
    type: io.kestra.plugin.core.output.OutputValues
    description: "Applies the blast radius cap to qualifying namespaces,
      partitioning into deletion targets, deferred items, and errors."
    values:
      to_delete: >-
        {{
          ((outputs.evaluate_candidates_loop.outputs is defined and outputs.evaluate_candidates_loop.outputs is not null) ? loopOutputs(outputs.evaluate_candidates_loop.outputs, 'verdict') : []) | jq(
            'map(select(.qualifies == true and .reason != "github_api_error"))[:' ~ inputs.max_deletions_per_run ~ ']'
          ) | first ?? []
        }}
      deferred: >-
        {{
          ((outputs.evaluate_candidates_loop.outputs is defined and outputs.evaluate_candidates_loop.outputs is not null) ? loopOutputs(outputs.evaluate_candidates_loop.outputs, 'verdict') : []) | jq(
            'map(select(.qualifies == true and .reason != "github_api_error"))[' ~ inputs.max_deletions_per_run ~ ':]'
          ) | first ?? []
        }}
      errors: >-
        {{
          ((outputs.evaluate_candidates_loop.outputs is defined and outputs.evaluate_candidates_loop.outputs is not null) ? loopOutputs(outputs.evaluate_candidates_loop.outputs, 'verdict') : []) | jq(
            'map(select(.reason == "github_api_error"))'
          ) | first ?? []
        }}

  - id: execute_cleanup
    type: io.kestra.plugin.core.flow.If
    description: "Executes planned namespace deletions or logs dry-run actions for
      namespaces qualifying under the cap."
    condition: "{{ (outputs.plan_actions.values.to_delete ?? []) | length > 0 }}"
    then:
      - id: check_dry_run_mode
        type: io.kestra.plugin.core.flow.If
        description: "Branches execution between dry-run reporting and live cluster
          deletion."
        condition: "{{ inputs.dry_run }}"
        then:
          - id: log_dry_run_plan
            type: io.kestra.plugin.core.flow.Loop
            description: "Logs planned namespace deletions without making cluster
              modifications."
            values: "{{ outputs.plan_actions.values.to_delete }}"
            concurrencyLimit: 1
            tasks:
              - id: log_dry_run_item
                type: io.kestra.plugin.core.log.Log
                message: "DRY RUN: would delete namespace {{ item.value.name }} (age: {{
                  item.value.age_hours }}h, PR: #{{ item.value.pr_number ??
                  'none' }}, reason: {{ item.value.reason }})"
        else:
          - id: delete_qualifying_namespaces
            type: io.kestra.plugin.scripts.shell.Commands
            description: "Deletes qualifying namespaces up to the blast radius cap using
              kubectl, re-checking the opt-in label before each delete and
              ignoring namespaces that are already gone."
            taskRunner:
              type: io.kestra.plugin.scripts.runner.docker.Docker
            containerImage: alpine/k8s:1.30.6
            allowFailure: true
            env:
              K8S_MASTER_URL: "{{ secret('K8S_MASTER_URL') }}"
              K8S_TOKEN: "{{ secret('K8S_TOKEN') }}"
              K8S_CA_CERT_DATA: "{{ secret('K8S_CA_CERT_DATA') }}"
              LABEL_SELECTOR: "{{ inputs.preview_label_selector }}"
              TARGET_NAMESPACES: >-
                {{ outputs.plan_actions.values.to_delete | jq('map(.name) |
                join(" ")') | first }}
            commands:
              - |
                set -eu
                printf '%s' "$K8S_CA_CERT_DATA" | base64 -d > ca.crt
                KUBECTL="kubectl --server=$K8S_MASTER_URL --token=$K8S_TOKEN --certificate-authority=ca.crt"
                failed=0
                for ns in $TARGET_NAMESPACES; do
                  if [ -z "$($KUBECTL get namespace "$ns" -l "$LABEL_SELECTOR" -o name 2>/dev/null)" ]; then
                    echo "SKIP: namespace $ns no longer exists or no longer matches '$LABEL_SELECTOR'"
                    continue
                  fi
                  if $KUBECTL delete namespace "$ns" --ignore-not-found --wait=false; then
                    echo "LIVE: deleted namespace $ns"
                  else
                    echo "ERROR: failed to delete namespace $ns"
                    failed=1
                  fi
                done
                exit $failed

  - id: notify_slack_summary
    type: io.kestra.plugin.core.flow.If
    description: "Dispatches a single consolidated Slack report when namespaces were
      deleted, planned in dry run, deferred by cap, or errored."
    condition: "{{ ((outputs.plan_actions.values.to_delete ?? []) | length > 0) or
      ((outputs.plan_actions.values.deferred ?? []) | length > 0) or
      ((outputs.plan_actions.values.errors ?? []) | length > 0) }}"
    then:
      - id: send_slack_report
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: "Posts sweep outcome details to the configured Slack incoming webhook."
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        retry:
          type: constant
          interval: PT5S
          maxAttempts: 3
        payload: |
          {{
            {
              "channel": inputs.slack_channel,
              "text": (inputs.dry_run ? ":mag: *Kubernetes Ephemeral Namespace Sweeper (DRY RUN)*" : ":broom: *Kubernetes Ephemeral Namespace Sweeper (LIVE)*"),
              "attachments": [
                {
                  "color": (
                    ((outputs.plan_actions.values.errors ?? []) | length > 0) ? "#E24A4A" :
                    inputs.dry_run ? "#3AA3E3" : "#36A64F"
                  ),
                  "blocks": [
                    {
                      "type": "section",
                      "text": {
                        "type": "mrkdwn",
                        "text": (inputs.dry_run ? "*Kubernetes Namespace Sweeper (DRY RUN)*" : "*Kubernetes Namespace Sweeper (LIVE)*") ~ "\n" ~
                                "*Execution ID:* `" ~ execution.id ~ "`\n" ~
                                "*Action Summary:* " ~
                                ((outputs.plan_actions.values.to_delete ?? []) | length) ~ (inputs.dry_run ? " planned for deletion" : " deleted") ~
                                ", " ~ ((outputs.plan_actions.values.deferred ?? []) | length) ~ " deferred by cap (max " ~ inputs.max_deletions_per_run ~ ")" ~
                                ", " ~ ((outputs.plan_actions.values.errors ?? []) | length) ~ " error(s)."
                      }
                    },
                    {
                      "type": "section",
                      "text": {
                        "type": "mrkdwn",
                        "text": "*Target Namespaces:*\n" ~ (
                          ((outputs.plan_actions.values.to_delete ?? []) | length > 0) ?
                          ((outputs.plan_actions.values.to_delete ?? []) | jq('map("• `" + .name + "`: age " + (.age_hours | tostring) + "h | PR #" + (.pr_number // "none") + " (" + .pr_state + ") | reason: " + .reason + " | action: " + (if ' ~ inputs.dry_run ~ ' then "WOULD_DELETE" else "DELETED" end)) | join("\n")') | first) :
                          "None"
                        )
                      }
                    },
                    (
                      ((outputs.plan_actions.values.deferred ?? []) | length > 0) ?
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "*Deferred by Cap (max " ~ inputs.max_deletions_per_run ~ " per sweep):*\n" ~
                                  ((outputs.plan_actions.values.deferred ?? []) | jq('map("• `" + .name + "`: age " + (.age_hours | tostring) + "h | PR #" + (.pr_number // "none") + " (" + .pr_state + ") | reason: " + .reason + " | action: DEFERRED") | join("\n")') | first)
                        }
                      } :
                      null
                    ),
                    (
                      ((outputs.plan_actions.values.errors ?? []) | length > 0) ?
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "*GitHub API Errors (Namespace skipped):*\n" ~
                                  ((outputs.plan_actions.values.errors ?? []) | jq('map("• `" + .name + "`: " + .error) | join("\n")') | first)
                        }
                      } :
                      null
                    )
                  ] | jq('map(select(. != null))') | first
                }
              ]
            } | toJson
          }}

  - id: fail_on_github_errors
    type: io.kestra.plugin.core.flow.If
    description: "Fails the workflow execution if any GitHub API queries failed,
      preventing silent failures while preserving the Slack summary."
    condition: "{{ (outputs.plan_actions.values.errors ?? []) | length > 0 }}"
    then:
      - id: abort_on_errors
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "One or more GitHub PR lookups failed during namespace evaluation:
          {{ outputs.plan_actions.values.errors | toJson }}"