Configuration Management

Advanced configuration management techniques in Pylee including secret handling, template interpolation, and multi-context processing

Configuration Management

Pylee’s configuration management system provides sophisticated tools for handling complex deployment scenarios, secret management, and dynamic configuration generation. This system supports multiple contexts, template interpolation, and secure secret handling across different environments.

Overview

The configuration management system in Pylee handles:

• Multi-context processing: Different configuration contexts for display, copy, and execution
• Template interpolation: Dynamic value substitution using flexible template syntax
• Secret handling: Secure management of sensitive information with context-aware redaction
• Environment-specific configuration: Seamless switching between development, staging, and production
• Configuration generation: Automated generation of connection strings, commands, and environment variables

Configuration Contexts

Display Context

Used for showing configuration in the UI with secrets masked for security:

{
  "environment": {
    "API_KEY": "[redacted]",
    "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db",
    "DEBUG": "true"
  }
}

Copy Context

Provides full configuration values for copying to clipboard or external tools:

{
  "environment": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "DEBUG": "true"
  }
}

Execution Context

Contains fully resolved configuration for runtime execution:

{
  "environment": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "DEBUG": "true",
    "COMPUTED_HASH": "abc123def456"
  }
}

Template Interpolation

Basic Syntax

Pylee supports flexible template interpolation using curly brace syntax:

{
  "remoteUrl": "https://{HOST}:{PORT}/api/v1",
  "environment": {
    "API_ENDPOINT": "{PROTOCOL}://{HOST}/api",
    "DATABASE_URL": "postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:5432/{DB_NAME}"
  }
}

Variable Prefixes

Use prefixes to explicitly reference variables or secrets:

{
  "environment": {
    "API_KEY": "{secret.API_KEY}",
    "DEBUG_MODE": "{var.DEBUG_MODE}",
    "MIXED_CONFIG": "{PROTOCOL}://{var.HOST}:{PORT}/api?key={secret.API_KEY}"
  }
}

Precedence Resolution

Variables and secrets are resolved with the following precedence:

1. Server level: Most specific configuration
2. Registry level: Shared configuration across servers
3. Organization level: Global organizational defaults

{
  "organization": {
    "variables": { "API_VERSION": "v1" },
    "secrets": { "MASTER_KEY": "org-secret" }
  },
  "registry": {
    "variables": { "API_VERSION": "v2" },
    "secrets": { "SERVICE_KEY": "registry-secret" }
  },
  "server": {
    "variables": { "DEBUG": "true" },
    "secrets": { "API_KEY": "server-secret" }
  }
}

Result: API_VERSION: "v2" (registry overrides organization)

Secret Management

Secure Storage

Secrets are stored securely and only exposed in appropriate contexts:

{
  "secrets": {
    "api_key": {
      "value": "sk-1234567890abcdef",
      "description": "External API authentication key",
      "rotationPolicy": "monthly"
    },
    "database_password": {
      "value": "complex-password-123",
      "description": "Database connection password",
      "rotationPolicy": "quarterly"
    }
  }
}

Context-Aware Redaction

Different contexts receive different levels of secret exposure:

{
  "displayContext": {
    "API_KEY": "[redacted]",
    "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db"
  },
  "copyContext": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:complex-password-123@host:5432/db"
  }
}

Multi-Level Secret Resolution

Secrets can be defined at multiple levels with proper precedence:

{
  "organizationSecrets": {
    "GLOBAL_API_KEY": "org-key-123"
  },
  "registrySecrets": {
    "SHARED_SECRET": "registry-secret-456"
  },
  "serverSecrets": {
    "LOCAL_TOKEN": "server-token-789"
  }
}

Configuration Generation

Dynamic Configuration Snippets

Generate configuration for different tools and environments:

{
  "configurationTemplates": {
    "docker": {
      "template": "docker run -e API_KEY={secret.API_KEY} -e DEBUG={var.DEBUG} myapp",
      "contexts": ["copy", "execution"]
    },
    "kubernetes": {
      "template": {
        "apiVersion": "v1",
        "kind": "Secret",
        "metadata": {
          "name": "app-secrets"
        },
        "data": {
          "api-key": "{secret.API_KEY|base64}",
          "db-password": "{secret.DB_PASSWORD|base64}"
        }
      }
    }
  }
}

Environment-Specific Generation

Generate different configurations based on environment:

{
  "environments": {
    "development": {
      "variables": {
        "API_URL": "http://localhost:3000",
        "DEBUG": "true"
      }
    },
    "production": {
      "variables": {
        "API_URL": "https://api.production.com",
        "DEBUG": "false"
      }
    }
  }
}

Advanced Features

Nested Configuration Processing

Handle complex nested configurations:

{
  "configuration": {
    "database": {
      "host": "{DB_HOST}",
      "port": "{DB_PORT}",
      "credentials": {
        "username": "{DB_USER}",
        "password": "{secret.DB_PASSWORD}"
      },
      "options": {
        "ssl": "{var.DB_SSL_ENABLED}",
        "timeout": "{var.DB_TIMEOUT}"
      }
    }
  }
}

Configuration Validation

Ensure configuration integrity:

{
  "validation": {
    "required": ["API_KEY", "DATABASE_URL"],
    "types": {
      "API_KEY": "string",
      "PORT": "number",
      "DEBUG": "boolean"
    },
    "patterns": {
      "API_KEY": "^sk-[a-zA-Z0-9]{32}$",
      "DATABASE_URL": "^postgresql://.*$"
    }
  }
}

Configuration Inheritance

Support configuration inheritance and overrides:

{
  "baseConfiguration": {
    "environment": {
      "NODE_ENV": "{var.ENVIRONMENT}",
      "LOG_LEVEL": "{var.LOG_LEVEL}"
    }
  },
  "serverConfiguration": {
    "extends": "baseConfiguration",
    "environment": {
      "SERVICE_NAME": "{var.SERVICE_NAME}",
      "PORT": "{var.PORT}"
    }
  }
}

Integration Patterns

Connect Button Integration

The ConnectButton component uses advanced configuration management:

{
  "connectButton": {
    "displayConfig": {
      "command": "docker run -e API_KEY=[redacted] myapp",
      "environment": {
        "API_KEY": "[redacted]",
        "DEBUG": "true"
      }
    },
    "copyConfig": {
      "command": "docker run -e API_KEY=sk-1234567890abcdef myapp",
      "environment": {
        "API_KEY": "sk-1234567890abcdef",
        "DEBUG": "true"
      }
    }
  }
}

URL Handler Integration

Generate complete configurations for external tools:

{
  "urlHandlers": {
    "cursor": {
      "url": "vscode://file{PROJECT_PATH}",
      "environment": {
        "WORKSPACE_PATH": "{var.PROJECT_PATH}",
        "API_KEY": "{secret.API_KEY}",
        "CONFIG_FILE": "{var.CONFIG_FILE_PATH}"
      }
    },
    "code": {
      "url": "code://file{PROJECT_PATH}",
      "environment": {
        "WORKSPACE_PATH": "{var.PROJECT_PATH}",
        "DEVELOPMENT_MODE": "{var.DEBUG}"
      }
    }
  }
}

Best Practices

Security Guidelines

• Never log secret values in plain text
• Use context-appropriate secret exposure
• Implement proper access controls
• Regular secret rotation and auditing

Configuration Organization

• Group related configuration together
• Use descriptive variable and secret names
• Implement consistent naming conventions
• Document configuration dependencies

Template Management

• Use clear, readable template syntax
• Implement proper error handling for missing variables
• Test template interpolation across all contexts
• Validate generated configurations

Environment Management

• Maintain separate configurations for each environment
• Use environment-specific variable overrides
• Implement proper configuration validation
• Test configuration generation in all environments

Error Handling

Template Resolution Errors

Handle missing variables gracefully:

{
  "errorHandling": {
    "missingVariables": "leave-placeholder",
    "invalidTemplates": "log-and-skip",
    "secretAccessDenied": "use-fallback"
  }
}

Configuration Validation Errors

Provide clear error messages:

{
  "validationErrors": {
    "required": "Variable '{name}' is required but not provided",
    "type": "Variable '{name}' expected {expected} but got {actual}",
    "pattern": "Variable '{name}' does not match required pattern"
  }
}

Performance Considerations

Caching Strategy

• Cache resolved configurations per context
• Implement invalidation on variable/secret changes
• Use lazy loading for expensive operations
• Optimize template compilation

Memory Management

• Limit configuration size
• Clean up unused configurations
• Use weak references where appropriate
• Monitor memory usage patterns

Troubleshooting

Common Issues

Template Not Resolving

Error: Template '{API_KEY}' could not be resolved

Solutions:

• Check variable/secret exists at appropriate level
• Verify access permissions
• Ensure correct template syntax

Context Mismatch

Error: Secret exposed in display context

Solutions:

• Review context configuration
• Check secret handling rules
• Verify UI component implementation

Precedence Issues

Error: Expected 'production' but got 'development'

Solutions:

• Review precedence rules
• Check environment configuration
• Verify variable override hierarchy

Debugging Tools

Enable configuration debugging:

{
  "debug": {
    "configurationManagement": {
      "enabled": true,
      "logTemplateResolution": true,
      "logSecretAccess": false,
      "logContextSwitching": true
    }
  }
}

Migration Guide

From Legacy System

When migrating from older configuration systems:

1. Audit existing configurations for security issues
2. Map legacy variables to new template syntax
3. Implement proper secret handling with context awareness
4. Test all configuration contexts thoroughly
5. Validate generated configurations in all environments

Template Syntax Migration

Convert legacy templates to new format:

{
  "legacy": "${{ secrets.API_KEY }}",
  "new": "{secret.API_KEY}"
}

Next Steps

• Learn about Template Interpolation for detailed syntax
• Explore Variables for non-sensitive configuration
• Check Secrets for sensitive data management
• Review Server configuration for complete examples