​Best ​Practices for ​Secrets in ​Kestra

A quick guide to secrets management best practices in Kestra.

Kestra provides a built-in secret manager with obfuscation capabilities, but it’s important to understand its limitations and follow best practices 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 not foolproof.
Current log obfuscation replaces full secret matches with ****. However, if a secret is modified—for example, through substring extraction, concatenation, encoding, or interpolation—it may bypass obfuscation and appear in logs. Refer to the String Expressions documentation for a list of possible transformations.

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:

Best practices:

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

Understand expression evaluation limits

When using the Debug Expression tool in the Outputs tab of an execution, Kestra forbids direct calls to secret() to prevent leaks. Logs are more permissive because tasks can emit any property, but this also increases the risk of accidental exposure.

Avoid using secrets in Log tasks. If they are required, ensure you understand the risks and limitations before doing so.

Avoid root-level secret placement

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

Best practices:

• Store secrets at the lowest namespace level necessary for their use.
• Use granular RBAC permissions to control who can access secrets and which workflows can use them.

Design workflows to limit exposure

Follow these practices when designing workflows:

• Pass secrets only to tasks that require them.
• Avoid exposing secrets in user-facing outputs or debug messages.
• Where possible, design tasks to reference secrets rather than embedding raw values directly.