Namespace is a logical grouping of flows. Namespaces are used to organize workflows and manage access to secrets, task 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. And as filesystems, namespaces can be indefinitely nested.

Hierarchical structure when using nested namespaces

Using the dot . symbol, you can add hierarchical structure to your namespaces which allows 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 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:

yaml
id: hello_world
namespace: marketing
tasks:
  - id: log_task
    type: io.kestra.core.tasks.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:

namespace_mgmt_1

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

namespace_mgmt_2