ServiceAccountWatch: Kubernetes unused ServiceAccount auditor blueprint for Kestra

id: serviceaccountwatch
namespace: company.team
description: Audits ServiceAccounts no pod uses and reports the unused ones on
  Slack. With delete_after_approval on, a cluster admin approves at a Pause gate
  before anything is deleted. Off by default, it never deletes.

labels:
  project: serviceaccountwatch
  team: platform

inputs:
  - id: namespace
    type: STRING
    displayName: "Namespace"
    description: the namespace whose ServiceAccounts to audit
    defaults: default
  - id: delete_after_approval
    type: BOOL
    displayName: "Delete after approval"
    description: when true, the run pauses for a cluster admin to approve, then
      deletes the reported unused ServiceAccounts. when false (default), the
      flow only reports and never deletes
    defaults: false
  - id: slack_webhook
    type: STRING
    displayName: "Slack Webhook URL"
    description: Incoming webhook URL of the Slack channel for the report

triggers:
  - id: schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: audits unused ServiceAccounts every morning
    cron: "30 8 * * *"
    timezone: UTC
    inputs:
      namespace: default
      delete_after_approval: false
      slack_webhook: "{{ secret('SLACK_WEBHOOK') }}"

tasks:
  - id: get_accounts
    type: io.kestra.plugin.kubernetes.kubectl.Get
    description: lists the namespace's ServiceAccounts with the Kubernetes plugin task
    connection:
      masterUrl: "{{ secret('MASTERURL') }}"
      oauthToken: "{{ secret('K8S_TOKEN') }}"
      trustCerts: true
    namespace: "{{ inputs.namespace }}"
    resourceType: serviceaccounts
    fetchType: FETCH

  - id: list_pods
    type: io.kestra.plugin.scripts.shell.Commands
    description: lists the namespace's pods as JSON
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
      user: "0"
    containerImage: bitnami/kubectl
    inputFiles:
      client.crt: "{{ secret('CLIENT_CRT') }}"
      client.key: "{{ secret('CLIENT_KEY') }}"
    commands:
      - kubectl get pods -n {{ inputs.namespace }} -o json
        --client-certificate=client.crt --client-key=client.key --server={{
        secret('MASTERURL') }} --insecure-skip-tls-verify=true > pods.json
    outputFiles:
      - pods.json

  - id: find_unused
    type: io.kestra.plugin.scripts.python.Script
    description: cross-references ServiceAccounts against the pods that use them
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
      user: "0"
    containerImage: python:3.11
    dependencies:
      - kestra
    inputFiles:
      pods.json: "{{ outputs.list_pods.outputFiles['pods.json'] }}"
    script: |
      import json
      from kestra import Kestra

      namespace = """{{ inputs.namespace }}"""

      # ServiceAccount names from the Kubernetes plugin Get task
      sa_names = [m['name'] for m in json.loads("""{{ outputs.get_accounts.metadataItems }}""")]

      with open('pods.json') as f:
          pods = json.load(f)['items']

      # ServiceAccount names we already reported, from the KV store (null on first run -> empty)
      raw_state = """{{ kv('serviceaccountwatch-state-' ~ inputs.namespace, errorOnMissing=false) }}"""
      already = set(json.loads(raw_state) if raw_state.strip() else [])

      # every pod counts as a reference, whatever its phase: a completed job's
      # account is still provisioned for the next run. a pod with no explicit
      # serviceAccountName runs as 'default'.
      used = set()
      for pod in pods:
          used.add(pod.get('spec', {}).get('serviceAccountName') or 'default')

      unused = sorted(n for n in sa_names if n not in used)
      new = [n for n in unused if n not in already]

      lines = [f"*ServiceAccountWatch - unused ServiceAccounts in '{namespace}'*", ""]
      for n in new:
          lines.append(f"- *{n}*: no pod in this namespace runs as it")
      lines.append("")
      lines.append("an account nothing uses is attack surface with no owner. if it has bindings, deleting it blind can break whoever still holds its token, so deleting one stays a human call.")
      alert_text = "\n".join(lines)

      Kestra.outputs({
          'new_unused': new,
          'count': len(new),
          'alert_text': alert_text,
          'new_state_json': json.dumps(unused),
      })

  - id: maybe_alert
    type: io.kestra.plugin.core.flow.If
    description: reports only newly found unused ServiceAccounts
    condition: "{{ outputs.find_unused.vars.count > 0 }}"
    then:
      - id: send_alert
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: posts the unused ServiceAccount report to Slack
        url: "{{ inputs.slack_webhook }}"
        messageText: "{{ outputs.find_unused.vars.alert_text }}"

  - id: save_state
    type: io.kestra.plugin.core.kv.Set
    description: remembers who was reported, so cleaned-up accounts drop out quietly
    key: "serviceaccountwatch-state-{{ inputs.namespace }}"
    value: "{{ outputs.find_unused.vars.new_state_json }}"
    overwrite: true

  - id: maybe_cleanup
    type: io.kestra.plugin.core.flow.If
    description: cleanup runs only when the caller opted in and there is something to clean
    condition: "{{ inputs.delete_after_approval and outputs.find_unused.vars.count > 0 }}"
    then:
      - id: approve_cleanup
        type: io.kestra.plugin.core.flow.Pause
        description: waits for a cluster admin to approve deleting the reported
          ServiceAccounts
        pauseDuration: PT24H
        behavior: CANCEL
        onResume:
          - id: approved
            description: Approve deletion of the unused ServiceAccounts listed in the report
            type: BOOL
            defaults: false
      - id: check_approval
        type: io.kestra.plugin.core.flow.If
        description: deletes only when the approver explicitly approved
        condition: "{{ outputs.approve_cleanup.onResume.approved == true }}"
        then:
          - id: delete_unused
            type: io.kestra.plugin.core.flow.Loop
            description: deletes each reported unused ServiceAccount
            values: "{{ outputs.find_unused.vars.new_unused }}"
            tasks:
              - id: delete_one
                type: io.kestra.plugin.scripts.shell.Commands
                description: deletes one ServiceAccount
                taskRunner:
                  type: io.kestra.plugin.scripts.runner.docker.Docker
                  user: "0"
                containerImage: bitnami/kubectl
                inputFiles:
                  client.crt: "{{ secret('CLIENT_CRT') }}"
                  client.key: "{{ secret('CLIENT_KEY') }}"
                commands:
                  - kubectl delete serviceaccount {{ item.value }} -n {{
                    inputs.namespace }} --ignore-not-found=true
                    --client-certificate=client.crt --client-key=client.key
                    --server={{ secret('MASTERURL') }}
                    --insecure-skip-tls-verify=true
          - id: send_deleted
            type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
            description: confirms which ServiceAccounts were deleted after approval
            url: "{{ inputs.slack_webhook }}"
            messageText: "ServiceAccountWatch cleanup approved and done. Deleted: {{
              outputs.find_unused.vars.new_unused | join(', ') }}"

How it works

get_accounts (io.kestra.plugin.kubernetes.kubectl.Get) lists the namespace's ServiceAccounts with the Kubernetes plugin task.
list_pods (io.kestra.plugin.scripts.shell.Commands) dumps the namespace's pods as JSON with kubectl. Pods stay on kubectl because the plugin Get output carries metadata and status only, and the cross-reference needs spec.serviceAccountName, which is not in there.
find_unused (io.kestra.plugin.scripts.python.Script) builds the set of accounts pods actually run as (a pod with no explicit serviceAccountName runs as default) and flags every ServiceAccount outside that set. It compares against the KV state so only newly found unused accounts are reported.
maybe_alert (io.kestra.plugin.core.flow.If) posts the Slack report only when there is someone new to name.
save_state (io.kestra.plugin.core.kv.Set) writes back the current unused list. Deleted accounts drop out on their own, so a reappearing unused account reports again, and steady-state reruns stay quiet.
maybe_cleanup (io.kestra.plugin.core.flow.If) runs only when delete_after_approval is on and there is something to clean. approve_cleanup (io.kestra.plugin.core.flow.Pause) halts the run until a cluster admin resumes it from the UI with approval; if nobody responds within 24 hours the run cancels and nothing is deleted. check_approval then deletes each reported account (kubectl delete serviceaccount, one per account) and posts a Slack confirmation naming what was deleted.

What you get

A daily audit of ServiceAccounts nothing runs as: stale accounts left behind by removed workloads and renamed deploys.
Slack reports naming each unused account, once, until the list changes.
A cleanup path that is human-gated, not automatic: with delete_after_approval on, deletion happens only after an admin approves the exact list at the Pause gate.
Quiet runs when every account in the namespace has a pod behind it, and no deletion ever when the input is off (the default).

Who it's for

Anyone whose namespaces have accumulated ServiceAccounts over months of deploys and wants the cleanup list, plus an approval-gated way to act on it without handing a bot standing delete rights over identity objects. Pairs with RBACWatch: this one covers unused accounts, that one covers over-powerful bindings.

Why orchestrate this with Kestra

kubectl get sa never told you which accounts are dead, and deleting them by hand is the kind of cleanup that never happens. As a flow it audits on a schedule, keeps every run's findings where you can review them, only bothers you when a new unused account appears, and puts the delete decision in front of a human with the list attached. Kestra holds the cluster credentials as secrets out of the YAML.

Prerequisites

A Kubernetes cluster with ServiceAccounts and pods you can list.
A kubeconfig client certificate and key with permission to list pods and delete ServiceAccounts in the target namespace (for the kubectl steps).
A ServiceAccount token with permission to list ServiceAccounts in the target namespace (for the plugin Get task). On minikube: create a ServiceAccount, bind it the view ClusterRole, and mint a token with kubectl create token.
Kestra with the Docker task runner available (used for the kubectl and Python steps).
A Slack Incoming Webhook URL.

Secrets

Secret	What it is
`CLIENT_CRT`	base64-encoded client certificate from your kubeconfig
`CLIENT_KEY`	base64-encoded client key from your kubeconfig
`MASTERURL`	base64-encoded Kubernetes API server URL, reachable from inside the Kestra container
`K8S_TOKEN`	base64-encoded ServiceAccount token for the plugin Get task
`SLACK_WEBHOOK`	base64-encoded Slack Incoming Webhook URL

In Kestra OSS, secrets come from environment variables prefixed with SECRET_ and must be base64-encoded. If the API URL uses 127.0.0.1 or localhost, replace it with host.docker.internal so the Kestra container can reach it. trustCerts is on for the plugin task because minikube serves a self-signed certificate; on a cluster with a proper CA, drop it.

Quick start

Start Kestra with the secrets above as SECRET_ environment variables. If minikube restarted since your last run, regenerate SECRET_MASTERURL first: the API port changes on every minikube start. Mint the token: kubectl create serviceaccount kestra-reader -n default, kubectl create clusterrolebinding kestra-reader --clusterrole=view --serviceaccount=default:kestra-reader, then kubectl create token kestra-reader -n default and base64-encode it as SECRET_K8S_TOKEN.
Import this flow and create two ServiceAccounts: kubectl create sa orphan-sa (nothing uses it) and kubectl create sa used-sa, plus a pod that runs as used-sa. Run the flow with defaults: the Slack report names only orphan-sa, and nothing is deleted.
Run again: quiet, already reported.
Run with delete_after_approval: true: the report posts, then the run pauses. Resume it from the execution's Gantt tab with approval checked: orphan-sa is deleted and a Slack confirmation names it. kubectl delete sa orphan-sa and run again: quiet, it dropped out of state.

How to extend

Cross-reference RoleBindings too, and split the report into accounts with bindings (risky) and accounts with none (safe cleanup).
Audit every namespace by wrapping the flow in a Loop over a namespace list.
Age the findings: only offer deletion for accounts unused for more than N days using creationTimestamp.
Shorten or lengthen the approval window by changing pauseDuration; behavior: CANCEL keeps the no-response case safe by cancelling instead of deleting.

Inputs

Input	Type	Default	What it does
`namespace`	STRING	`default`	the namespace whose ServiceAccounts to audit
`delete_after_approval`	BOOL	`false`	when true, pause for admin approval and then delete the reported unused ServiceAccounts. when false, report only
`slack_webhook`	STRING	(required)	Incoming webhook URL of the Slack channel for the report

Pitfalls

Deletion is off by default. With delete_after_approval off, this flow is strictly read-only and never touches an account, whatever the report says.
With approval on, the Pause gate is the only thing between the report and deletion. The approver must check the list in the Slack report before resuming; a resume without the approval box checked deletes nothing.
If nobody responds within 24 hours, behavior: CANCEL cancels the run. Nothing is deleted on timeout, by design.
An account that looks stale might belong to a CI job that runs monthly. That is exactly why deletion is approval-gated instead of automatic.
Every pod counts as a reference, including completed Job pods. Conservative on purpose: an account a finished job used is provisioned for its next run.
The default ServiceAccount is flagged when no pod runs as it. That is correct, and on a fresh namespace it may be the only finding.
The plugin Get task returns metadata and status only, which is why pods are still listed with kubectl: the cross-reference needs spec.serviceAccountName, and that field is not in the Get output.
After an approved deletion, the KV state still lists the deleted accounts until the next run, when they are gone from the listing and drop out on their own.
Minikube's API server port changes on every minikube start. Regenerate SECRET_MASTERURL and restart the Kestra container, or the steps fail to connect.