Kestra Orphaned Namespace Configuration Compliance Gate with Kestra

id: kestra-orphaned-namespace-configuration-compliance-gate
namespace: company.platform

description: |
  List every Kestra namespace that has a stored configuration and compare it against namespaces
  that actually contain a flow, classify how many exist with zero flows, alert Slack with the
  exact orphaned namespace names, and log a governance audit trail either way.

inputs:
  - id: kestra_url
    type: STRING
    displayName: Kestra API URL
    description: Base URL of the Kestra instance to audit.
    defaults: "http://localhost:8080"

  - id: namespace_prefix
    type: STRING
    displayName: Namespace prefix
    description: Only audit namespaces starting with this prefix. Leave empty to
      audit every namespace.
    defaults: ""

  - id: max_orphaned_count
    type: INT
    displayName: Max orphaned count
    description: Alert when this many or more namespaces have a stored configuration
      but zero flows.
    defaults: 1

tasks:
  - id: list_existing_namespaces
    type: io.kestra.plugin.kestra.namespaces.List
    description: Read-only probe. Lists every namespace backed by a stored
      configuration (namespace-level files or variables), excluding transient
      namespaces that only exist because a flow happens to reference them.
    allowFailure: true
    kestraUrl: "{{ inputs.kestra_url }}"
    auth:
      apiToken: "{{ secret('KESTRA_API_TOKEN') }}"
    prefix: "{{ inputs.namespace_prefix }}"
    existingOnly: true

  - id: list_namespaces_with_flows
    type: io.kestra.plugin.kestra.namespaces.NamespacesWithFlows
    description: Read-only probe. Lists every distinct namespace that currently owns
      at least one flow.
    allowFailure: true
    kestraUrl: "{{ inputs.kestra_url }}"
    auth:
      apiToken: "{{ secret('KESTRA_API_TOKEN') }}"
    prefix: "{{ inputs.namespace_prefix }}"

  - id: evaluate
    type: io.kestra.plugin.core.output.OutputValues
    description: Computes the set difference between namespaces with a stored
      configuration and namespaces that actually own a flow; whatever is left
      has configuration (and in many installs, namespace-level secrets or
      variables) with nothing using it.
    values:
      orphaned_count: >-
        {{ (outputs.list_existing_namespaces is not defined or
        outputs.list_namespaces_with_flows is not defined) ? -1 : (({'existing':
        outputs.list_existing_namespaces.namespaces, 'with_flows':
        outputs.list_namespaces_with_flows.namespaces} | jq('.with_flows as $wf
        | [.existing[] | select(. as $n | ($wf | index($n)) == null)] |
        length')) | first | number) }}
      orphaned_namespaces: >-
        {{ (outputs.list_existing_namespaces is not defined or
        outputs.list_namespaces_with_flows is not defined) ? '' : (({'existing':
        outputs.list_existing_namespaces.namespaces, 'with_flows':
        outputs.list_namespaces_with_flows.namespaces} | jq('.with_flows as $wf
        | [.existing[] | select(. as $n | ($wf | index($n)) == null)] | join(";
        ")')) | first) }}
      severity: >-
        {{ (outputs.list_existing_namespaces is not defined or
        outputs.list_namespaces_with_flows is not defined) ? 'PROBE_FAILED' :
        (((({'existing': outputs.list_existing_namespaces.namespaces,
        'with_flows': outputs.list_namespaces_with_flows.namespaces} |
        jq('.with_flows as $wf | [.existing[] | select(. as $n | ($wf |
        index($n)) == null)] | length')) | first | number) >=
        inputs.max_orphaned_count) ? 'ORPHANED_NAMESPACES_FOUND' : 'COMPLIANT')
        }}

  - id: route
    type: io.kestra.plugin.core.flow.Switch
    description: Branches on severity. Every case ends in a log or a Slack alert;
      the Kestra plugin has no task to delete a namespace, so clearing an
      orphaned one out is deliberately left as a human decision, not an
      automated one.
    value: "{{ outputs.evaluate.values.severity }}"
    cases:
      "COMPLIANT":
        - id: log_compliant
          type: io.kestra.plugin.core.log.Log
          message: "No namespace under prefix '{{ inputs.namespace_prefix }}' has a stored
            configuration with zero flows."
      "ORPHANED_NAMESPACES_FOUND":
        - id: alert_orphaned
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'ORPHANED_NAMESPACES_FOUND: ' ~ outputs.evaluate.values.orphaned_count ~ ' namespace(s) have a stored configuration but zero flows: ' ~ outputs.evaluate.values.orphaned_namespaces ~ '. Review whether their namespace-level files, variables, or secrets are still needed.'} | toJson }}
      "PROBE_FAILED":
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'PROBE_FAILED: could not list Kestra namespaces at ' ~ inputs.kestra_url ~ '. Check the KESTRA_API_TOKEN secret and that the URL is reachable.'} | toJson }}

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "Kestra orphaned namespace configuration compliance gate complete: {{
      outputs.evaluate.values.orphaned_count }} orphaned namespace(s), severity
      {{ outputs.evaluate.values.severity }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'Kestra orphaned namespace configuration compliance gate failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: weekly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled. Enable once KESTRA_API_TOKEN and
      SLACK_WEBHOOK_URL are set and kestra_url points at a real instance.
    cron: "0 8 * * 1"
    disabled: true
    inputs:
      kestra_url: "http://localhost:8080"
      namespace_prefix: ""
      max_orphaned_count: 1

A namespace in Kestra can end up with saved configuration, namespace-level files, variables, and in many installs secrets, long after every flow that used it has been deleted or moved elsewhere. Nothing in Kestra itself flags that gap: the namespace still exists, still holds whatever was configured in it, and nobody is looking at it anymore. This is Kestra auditing itself: it reads the real list of namespaces with a stored configuration, compares it against the real list of namespaces that still own a flow, and reports exactly which ones are left over.

This blueprint was created by Mohit Jeswani.

How it works

list_existing_namespaces (io.kestra.plugin.kestra.namespaces.List, existingOnly: true) lists every namespace backed by a stored configuration. Read-only.
list_namespaces_with_flows (io.kestra.plugin.kestra.namespaces.NamespacesWithFlows) lists every namespace that currently owns at least one flow. Read-only.
evaluate (io.kestra.plugin.core.output.OutputValues) computes the set difference between the two lists with a jq filter and classifies the result as COMPLIANT, ORPHANED_NAMESPACES_FOUND, or PROBE_FAILED.
route (io.kestra.plugin.core.flow.Switch) logs when clean, or posts the exact orphaned namespace names to Slack otherwise. The Kestra plugin has no task to delete a namespace, so clearing one out stays a human decision.
summary logs the orphaned count and severity, closing the governance cycle.
errors alerts Slack if the flow itself fails, for example an expired API token.

What you get

A real set difference computed from two live API calls, not a guess based on when someone remembers a team migrating away from a namespace.
The exact orphaned namespace names in the Slack alert, so a platform team can go review (and decide whether to clean up) each one directly.
A read-only check: nothing about a namespace or its configuration is changed.

Who it's for

Platform teams who run Kestra for multiple internal teams and want namespace sprawl caught automatically, not discovered during an annual cleanup.
Teams evaluating the Kestra plugin's own self-management tasks who want a worked example of namespaces.List and namespaces.NamespacesWithFlows used together as a compliance gate, distinct from this repo's existing Kestra self-management blueprint, which recovers stuck paused executions rather than auditing namespace configuration.

Why orchestrate this with Kestra

Kestra's own API can list namespaces and list namespaces with flows, but it has no policy comparing the two, no schedule, and no Slack integration of its own for this. Kestra keeps namespace_prefix and max_orphaned_count as flow inputs, turns two raw lists into a governance decision, and keeps a full execution history of every audit and which namespaces it flagged.

Prerequisites

A running Kestra instance (OSS or EE) reachable from the worker, with an API token that can read namespaces and flows.
At least one namespace with a saved configuration and zero flows, to confirm the orphaned-namespace path; create one by saving a namespace file or variable through the UI for a namespace with no flows in it.
A Slack incoming webhook URL.

The official kestra/kestra Docker image (docker run kestra/kestra server local) is the standard way to run a local Kestra instance for testing this blueprint against itself.

Secrets

KESTRA_API_TOKEN: the Kestra API token used by both probe tasks. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_KESTRA_API_TOKEN.
SLACK_WEBHOOK_URL: used by both Slack alert cases and the errors block. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_SLACK_WEBHOOK_URL.

Inputs

Input	Default	Purpose
`kestra_url`	`http://localhost:8080`	Kestra instance to audit
`namespace_prefix`	`` (empty)	Scope the audit to namespaces starting with this prefix
`max_orphaned_count`	`1`	Orphaned-namespace count that triggers the Slack alert

Outputs

{{ outputs.list_existing_namespaces.namespaces }} / {{ outputs.list_namespaces_with_flows.namespaces }}: the two raw namespace lists, as Kestra's own API reports them.
{{ outputs.evaluate.values.orphaned_count }} / .orphaned_namespaces: how many namespaces are orphaned and their names, semicolon-joined.
{{ outputs.evaluate.values.severity }}: COMPLIANT, ORPHANED_NAMESPACES_FOUND, or PROBE_FAILED.

Pitfalls

existingOnly: true on namespaces.List excludes transient namespaces (ones that only exist implicitly because a flow references them); verified directly against the task's own description, since this is the exact flag that makes the comparison meaningful; without it, every namespace a flow references would already count as "existing" and the diff would find nothing.
What counts as "stored configuration" depends on your Kestra edition: OSS namespaces carry files and variables, EE adds more namespace-level resources. This blueprint does not distinguish between them, it only reports that a stored configuration exists with no flow behind it.
Both probe tasks default to fetching every page when page is left unset; a very large number of namespaces makes each run take proportionally longer.

Quick start

Add the KESTRA_API_TOKEN and SLACK_WEBHOOK_URL secrets.
Run a local Kestra instance via docker run kestra/kestra server local and create a namespace-level variable for a namespace with no flows in it.
Run the flow manually and confirm alert_orphaned fires naming that namespace.
Add a flow to that namespace and run again; confirm log_compliant fires instead.
Enable the weekly trigger once namespace_prefix reflects the scope you want audited.

How to extend

Chain a lookup of each orphaned namespace's stored files via the Kestra API to summarize what configuration is actually sitting unused, not just the namespace name.
Scope namespace_prefix per team and deploy one copy of this flow per team's namespace tree, routing each team's Slack alert to its own channel.
Add an approval-gated cleanup flow downstream that a human can trigger manually after reviewing the orphaned list, since no automated delete path exists.

Kestra Orphaned Namespace Configuration Compliance Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Outputs

Pitfalls

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Kestra Orphaned Namespace Configuration Compliance Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Outputs

Pitfalls

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Kestra Flow Security, Governance and Linting Gate

Kestra instance retention policy with dry run, approval and audit CSV

Kestra Flow Failure Rate Gate

Promote Kestra flows from staging to production with approval, snapshot and rollback

Kestra Schedule Trigger Health Sentinel

Purge aged Kestra execution history behind an approval gate

New to Kestra?