​Namespace

Namespace is a logical grouping of flows.

Namespaces are used to organize workflows and manage access to secrets, plugin defaults and variables.

You can think of a namespace as a folder for your flows. Similar to folders on your file system, namespaces can be used to organize flows into logical categories. Similar to filesystems, namespaces can be indefinitely nested.

If you're looking to completely isolate environments with their own resources on the same Kestra instance, you should look at Tenants that are part of the Enterprise Edition.

Hierarchical structure when using nested namespaces

Using the dot . symbol, you can add a hierarchical structure to your namespaces which allows you to logically separate environments, projects, teams and departments. This way, your product, engineering, marketing, finance, and data teams can all use the same Kestra instance, while keeping their flows organized and separated. Various stakeholders can have their own child namespaces that belong to a parent namespace grouping them by environment, project, or team.

Namespace name

A namespace name can be built from alphanumerical characters, optionally separated by .. The hierarchy depth for namespaces is unlimited. Here are some examples of namespaces:

• project_one
• company.project_two
• company.team.project_three

Using namespaces to organize flows and files

When you create a flow, you can assign a namespace to it:

id: hello_world
namespace: company.team
tasks:
  - id: log_task
    type: io.kestra.plugin.core.log.Log
    message: hi from {{ flow.namespace }}

Here, the flow is assigned to the marketing namespace. This assignment of a namespace to a flow already provides a benefit of improved organization and filtering:

Additionally, you can organize your code on a namespace-level using the embedded Code editor and Namespace Files, with the option to sync those files from Git:

Namespace Tab

Starting 0.18.0, Kestra has introduced the Namespaces tab in the Kestra UI for OSS. In this tab, you can see all the namespaces associated with the different flows in Kestra.

You can open the details about any namespace by clicking on the name or details button to the right of that namespace.

When you select the details button for any namespace, the namespace overview page opens which details the executions of flows in that namespace.

On the top of this page, you have different tabs:

1. Overview: This is the default landing page of the Namespace. This page contains the dashboards and summary about the executions of different flows in this namespace.
2. Editor: the in-built editor where you can add/edit the namespaceFiles.
3. Flows: shows all the flows in the namespace. It gives a brief about each of the flows including the flow ID, labels, last execution date and last execution status, and the execution statistics. By selecting the details button on the right of the flow, you can navigate to that flow's page.
4. Dependencies: shows all the flows and which ones are dependent on each other (for example through Subflows or Flow Triggers).
5. KV Store: manage the key-values pairs associated with this namespace. More details on KV Store can be found here.

The other tabs: Edit, Variables, Plugin Defaults, Secrets and Audit Logs are only available for Kestra EE. More details about them can be found here.