​Best ​Practices for ​Secrets in ​Kestra

Check out a quick guide to secrets management best practices in Kestra.

Kestra provides an in-platform secret manager with built-in obfuscation, but it’s important to understand its limitations and how to minimize the risk of secret exposure.

Secret Obfuscation in Logs Is Best Effort

Kestra attempts to mask secrets in logs and during expression evaluation, but masking is never perfect. The current log obfuscation works by replacing full secret matches with ****. If a secret is transformed — for example, by substring extraction, concatenation, encoding, or interpolation — it may bypass the obfuscation and appear in logs. Refer to the String Expressions documentation for a list of possible abstractions.

For example, the following flow uses jq() in a log message to return a partial value associated with a secret:

id: secret_test
namespace: company.team

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: "You can see my secret token {{ secret('jsonSecret') | jq('.token') }}"

In the logs, the token name SUPER_SECRET is exposed:

We recommend the following best practices:

• Never log secrets intentionally.
• Avoid passing secrets into string manipulation expressions that could result in partial values being output.
• Treat secrets as sensitive at all times, even in debug or test workflows.

Understand Expression Evaluation Limits

When using the Debug Expression debugger in the Outputs tab of an execution, Kestra forbids direct calls to secret() entirely to prevent secret leaks. Logs are more permissive because tasks can emit any property, but this also increases the risk of accidental exposure. Therefore, avoid using secrets in Log tasks, and if they are necessary for some use case, then understand the limitations.

Avoid Root-Level Secret Placement

Secrets defined at the root namespace are inherited by all sub-namespaces. This can unintentionally broaden their accessibility and increase potential exposure.

We recommend the following best practices:

• Store secrets at the lowest namespace level necessary for their usage.
• This enables more granular RBAC permissions, limiting who can access the secret and in which workflows it can be used.

Design Workflows to Limit Exposure

We recommend the following best practices with designing flows:

• Pass secrets only to tasks that require them.
• Do not use secrets in user-facing outputs or debug messages.
• Where possible, design tasks to accept references to secrets rather than raw secret values.