Jinja2 templates

kdeps uses Jinja2-compatible templates (via gonja) as the unified template system for both project scaffolding and runtime YAML preprocessing. Preprocessing runs for every workflow and resource file in both modes.

YAML preprocessing

Every workflow and resource YAML file is preprocessed through Jinja2 before YAML parsing. This lets you:

• Conditionally include or exclude sections based on environment variables
• Inject environment values directly into YAML at parse time
• Strip comments before parsing

# workflow.yaml
apiVersion: kdeps.io/v1
kind: Workflow
metadata:
  name: my-api
  version: "1.0.0"
  targetActionId: response
settings:
  apiServer:
{% if env.PORT %}
    portNum: {{ env.PORT | int }}
{% else %}
    portNum: 8080
{% endif %}

Auto-protection of runtime API calls

kdeps automatically wraps all runtime API function calls ({{ get(...) }}, {{ set(...) }}, {{ info(...) }}, {{ input(...) }}, {{ output(...) }}, {{ file(...) }}, {{ item(...) }}, {{ loop(...) }}, {{ session(...) }}, {{ json(...) }}, {{ safe(...) }}, {{ debug(...) }}, {{ default(...) }}) in {% raw %}...{% endraw %} before Jinja2 renders the file. You do not need to add raw blocks manually.

Static Jinja2 expressions like {{ env.PORT }} are evaluated normally because they do not start with a kdeps API function name.

# resource.yaml - no {% raw %} needed
{% if env.ENABLE_HTTP == 'true' %}
  component:
    name: http_request
    with:
      method: GET
      url: "{{ get('url') }}"
      headers:
        X-Request-ID: "{{ info('request_id') }}"
{% endif %}

Available context variables

Variable	Type	Description
env	map[string]string	All current process environment variables

Template syntax

Variables

port: {{ env.PORT | int }}
name: {{ env.SERVICE_NAME | default('my-service') }}

Conditionals

{% if env.DEBUG == 'true' %}
  logLevel: debug
{% else %}
  logLevel: info
{% endif %}

Comments

{# This comment is stripped before parsing #}

Whitespace control

Use - to trim surrounding whitespace:

settings:
{%- if env.CERT_FILE %}
  certFile: {{ env.CERT_FILE }}
{%- endif %}

Scaffolding templates

Project scaffolding templates (used by kdeps new) also use Jinja2 with .j2 file extensions. Variables available in scaffolding templates:

Variable	Type	Description
name	string	Project name
description	string	Project description
version	string	Version string
port	int	API server port
resources	[]string	Enabled resource types

See also

• Expressions
• Unified API
• Jinja2 documentation