Advanced Configuration

This guide covers advanced configuration options for KDeps workflows.

Request Object

The request object provides access to HTTP request metadata in expressions.

Available Properties

Property	Type	Description
request.method	string	HTTP method (GET, POST, etc.)
request.path	string	Request path
request.ip	string	Client IP address
request.id	string	Unique request ID
request.sessionId	string	Session ID (if sessions enabled)

Usage Examples

apiVersion: kdeps.io/v1
kind: Resource
metadata:
  actionId: logRequest
run:
  expr:
    # Access request metadata
    - set('method', request.method)
    - set('path', request.path)
    - set('clientIp', request.ip)
    - set('requestId', request.id)
    - set('session', request.sessionId)

    # Build log entry
    - set('logEntry', json({
        "timestamp": info('request.id'),
        "method": get('method'),
        "path": get('path'),
        "ip": get('clientIp'),
        "requestId": get('requestId')
      }))

Request-Based Routing

run:
  expr:
    # Different behavior based on request method
    - set('isPost', request.method == 'POST')
    - set('isGet', request.method == 'GET')
  validations:
    skip:
      - "!get('isPost')"

Logging and Auditing

run:
  sql:
    connection: logs
    queries:
      - query: |
          INSERT INTO audit_log (request_id, method, path, ip, session_id, timestamp)
          VALUES (?, ?, ?, ?, ?, NOW())
        params:
          - "{{ request.id }}"
          - "{{ request.method }}"
          - "{{ request.path }}"
          - "{{ request.ip }}"
          - "{{ request.sessionId }}"

Agent Settings

The agentSettings section configures the runtime environment.

Complete Reference

settings:
  agentSettings:
    # Timezone
    timezone: "America/New_York"

    # Python Configuration
    pythonVersion: "3.11"
    pythonPackages:
      - numpy==1.26.0
      - pandas>=2.0.0
      - requests
    requirementsFile: "requirements.txt"
    pyprojectFile: "pyproject.toml"
    lockFile: "uv.lock"

    # System Packages
    packages:
      - ffmpeg
      - imagemagick
    osPackages:
      - libpq-dev
      - libxml2-dev
    repositories:
      - ppa:deadsnakes/ppa

    # Docker Configuration
    baseOS: "ubuntu"  # alpine, ubuntu, debian

    # Docker/Ollama Configuration
    ollamaImageTag: "0.3.0"

    # Environment
    args:
      BUILD_TYPE: production
    env:
      API_KEY: "${API_KEY}"
      DEBUG: "false"

Field Descriptions

Python Settings

Field	Description
pythonVersion	Python version (e.g., "3.11", "3.12")
pythonPackages	List of pip packages to install
requirementsFile	Path to requirements.txt
pyprojectFile	Path to pyproject.toml (for uv)
lockFile	Path to uv.lock file

System Packages

Field	Description
packages	System packages (installed via apt/apk)
osPackages	Additional OS-level libraries
repositories	Additional package repositories

Docker Settings

Field	Description
baseOS	Base Docker image OS
ollamaImageTag	Ollama Docker image version

Docker Settings (extended)

Field	Description
ollamaImageTag	Ollama Docker image version
installOllama	Force/suppress Ollama installation in image

LLM model is set per resource in run.chat.model. Backend, base URL, and API keys are configured in ~/.kdeps/config.yaml. See LLM Backends.

Environment

Field	Description
args	Build-time arguments
env	Runtime environment variables

SQL Connections

Define named database connections for reuse across resources.

Configuration

settings:
  sqlConnections:
    primary:
      connection: "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
      pool:
        maxConnections: 25
        minConnections: 5
        maxIdleTime: "30m"
        connectionTimeout: "10s"

    analytics:
      connection: "mysql://analyst:pass@analytics-db:3306/analytics"
      pool:
        maxConnections: 10
        minConnections: 2
        maxIdleTime: "15m"
        connectionTimeout: "5s"

    cache:
      connection: "sqlite://./cache.db"

Pool Configuration

Field	Default	Description
maxConnections	25	Maximum pool size
minConnections	5	Minimum idle connections
maxIdleTime	30m	Max time before idle connection is closed
connectionTimeout	10s	Connection acquisition timeout

Using Named Connections

run:
  sql:
    connection: primary  # Reference by name
    queries:
      - query: "SELECT * FROM users WHERE id = ?"
        params:
          - "{{ get('userId') }}"

Trusted Proxies

Configure trusted proxies for accurate client IP detection behind load balancers.

API Server

settings:
  apiServerMode: true
  apiServer:
    hostIp: "0.0.0.0"
    portNum: 16395
    trustedProxies:
      - "10.0.0.0/8"
      - "172.16.0.0/12"
      - "192.168.0.0/16"

Web Server

settings:
  webServerMode: true
  webServer:
    hostIp: "0.0.0.0"
    portNum: 16395
    trustedProxies:
      - "127.0.0.1"
      - "10.0.0.1"

Environment Variable Expansion

Use environment variables in configuration values.

Syntax

settings:
  agentSettings:
    env:
      # Direct reference
      API_KEY: "${API_KEY}"

      # With default value
      LOG_LEVEL: "${LOG_LEVEL:-info}"

      # Combined
      DATABASE_URL: "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/${DB_NAME}"

In SQL Connections

settings:
  sqlConnections:
    primary:
      connection: "postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}"

Multiple Route Definitions

Define multiple routes with different methods and paths.

settings:
  apiServerMode: true
  apiServer:
    portNum: 16395
    routes:
      # Chat endpoint
      - path: /api/v1/chat
        methods: [POST]

      # Search endpoint
      - path: /api/v1/search
        methods: [GET, POST]

      # CRUD operations
      - path: /api/v1/users
        methods: [GET, POST]
      - path: /api/v1/users/:id
        methods: [GET, PUT, DELETE]

      # Health check
      - path: /health
        methods: [GET]

See Also

• Workflow Configuration - Basic workflow configuration
• Session & Storage - Session persistence
• CORS - Cross-origin configuration
• Docker Deployment - Deployment options