Jsonnet: AI-Optimized Technical Reference

Technology Overview

Purpose: JSON/YAML configuration generation with programming capabilities
Primary Use Case: Managing 15+ similar Kubernetes/microservice configurations
Break-even Point: When copy-pasting YAML becomes more time-consuming than learning Jsonnet

Critical Implementation Decisions

Implementation Selection (CRITICAL)

Implementation	Status	Performance	Use Case
C++ (original)	AVOID	Slow, security warnings, abandoned	None
Go (go-jsonnet)	RECOMMENDED	2-3 seconds for 200 configs	Standard use
Sjsonnet (JVM)	Specialized	Fast execution, 0.5s startup penalty	1000+ configs only

Consequence: Choosing C++ implementation will cause significant productivity loss due to performance issues.

Installation Requirements

Platform-Specific Installation

# macOS (reliable)
brew install jsonnet

# Ubuntu/Debian (usually works)
sudo apt-get install jsonnet

# Windows (problematic)
# Use WSL2 - native Windows compilation is unreliable

# Python/CI environments
pip install gojsonnet  # Requires version 0.20.x+

Critical Warning: Versions before 0.20.x crash on real workloads.

Configuration Specifications

Directory Structure (Required for Sanity)

lib/           # Reusable templates
configs/       # Environment-specific configs
generated/     # Output directory (gitignored or committed based on GitOps strategy)

External Variables (Mandatory)

• External variables have no defaults - failure to provide causes immediate crash
• Use --ext-str variable=value for all external dependencies
• Alternative: Use local variables instead of std.extVar() for optional values

Import Path Resolution (Major Pain Point)

Critical Issue: Imports resolve relative to command execution directory, not file location

Solution Pattern:

# Wrong (will break randomly)
cd configs && jsonnet environments/prod.jsonnet

# Correct (always works)
jsonnet -J configs environments/prod.jsonnet

Performance Thresholds

Real-World Performance Data

• Go implementation: 200 configs = 2-3 seconds compile time, ~200MB memory
• C++ implementation: 200 configs = 8+ seconds (unacceptable for development)
• Sjsonnet: Fast execution but 0.5s startup kills development workflow

Scale Recommendations

• 1-5 services: Use Kustomize instead
• 5-15 services: Marginal - evaluate copy-paste pain vs learning time
• 15+ services: Jsonnet becomes beneficial
• 100+ services: Essential for maintainability

Critical Failure Modes

Import System Failures

Symptom: "Import not found" errors that work sometimes
Root Cause: Path resolution relative to execution directory
Solution: Always use -J flag with library paths

External Variable Crashes

Symptom: "External variable not defined" runtime crash
Root Cause: No default values for std.extVar()
Prevention: Provide all external variables or use local variables

Error Message Inadequacy

Issue: Complex files produce useless error messages
Workaround: Break large files into smaller, testable components
Debug Pattern: Test imports individually before composing

Resource Requirements

Learning Time Investment

• Basic usage: 1 day (for developers)
• Object inheritance/imports: 1 week of debugging
• Production-ready patterns: 2-3 weeks including path/error handling

Team Prerequisites

• Required: Programming background (functions, loops, conditionals)
• Helpful: Kubernetes YAML familiarity
• Blocker: Teams resistant to learning new tools

Integration Patterns

GitOps Strategy A: Generated Files Committed

# CI Pipeline
- name: Generate configs
  run: jsonnet -J lib -m generated/prod/ configs/prod.jsonnet
- name: Commit generated files
  run: |
    git add generated/
    git commit -m "Update generated configs"
    git push

Trade-off: Clean GitOps visibility vs cluttered git history

GitOps Strategy B: Build-Time Generation

• Generate configs in CI/CD only
• ArgoCD/Flux pulls generated artifacts
• Cleaner git history, more complex pipeline

CI/CD Integration Requirements

validation_pipeline:
  - jsonnet_compile: "Verify syntax and imports"
  - yaml_lint: "Validate generated YAML"
  - dry_run_apply: "Test Kubernetes admission"

Comparison Matrix

Tool	Learning Curve	Debugging Difficulty	Programming Capability	Community Size
Jsonnet	2-3 weeks	High (poor error messages)	Full programming	Small but dedicated
Helm	Template debugging nightmare	Very High (template errors)	Template gymnastics only	Large ecosystem
Kustomize	5 minutes	Low (clear errors)	YAML overlays only	Built into kubectl
Terraform	Reasonable	Medium (plan shows issues)	Yes (for infrastructure)	Large ecosystem

When NOT to Use Jsonnet

Definitive Rejection Criteria

• Small scale: <15 services with infrequent changes
• Team constraints: Groups that view learning tools as "unnecessary complexity"
• Existing solutions: Kustomize already solves your overlay needs
• Ecosystem dependency: Heavy reliance on Helm chart ecosystem

Alternative Solutions by Use Case

• Simple overlays: Kustomize
• Community charts: Helm
• Infrastructure: Terraform
• Real programming for config: Pulumi

Advanced Operational Intelligence

Object Inheritance Patterns

// Base template with safe defaults
local BaseService(name, port) = {
  replicas: 1,  // Conservative default
  resources: {
    requests: { memory: '128Mi', cpu: '100m' },
    limits: { memory: '256Mi', cpu: '200m' }
  }
};

// Team customization with '+' operator
local FrontendService(name, port) = BaseService(name, port) + {
  replicas: 3,  // Override for high availability
  metadata+: { 
    labels+: { team: 'frontend' }  // Additive merge
  }
};

Production Helper Functions

ConfigMap Generation:

configMapFromDir(name, path):: {
  // Automatically imports all files from directory
  data: std.foldl(
    function(acc, file) acc + { 
      [std.basename(file)]: importstr path + '/' + file 
    },
    std.objectFields(import path),
    {}
  )
}

Monitoring Integration Pattern

// Single service definition drives multiple outputs
local service = {
  name: 'user-service',
  port: 8080,
  sla: { latency_p99: 500, error_rate: 0.01 }
};

{
  'deployment.yaml': makeDeployment(service),
  'alerts.yaml': makePrometheusAlerts(service.sla),
  'dashboard.json': makeGrafanaDashboard(service)
}

Operational Benefit: Change SLA in one place, all monitoring components update consistently.

Troubleshooting Decision Tree

Performance Issues

1. Check implementation: C++ → Switch to Go immediately
2. Check for circular imports: Use jsonnet lint
3. Profile large files: Break into smaller modules

Import Failures

1. Verify execution directory: Use -J with absolute library paths
2. Test imports individually: jsonnet -e 'import "lib/module.jsonnet"'
3. Check file permissions: Common in containerized CI environments

Runtime Crashes

1. External variables: Provide all required --ext-str parameters
2. Field access errors: Use defensive programming with std.objectHas()
3. Type mismatches: Jsonnet is dynamically typed but strict at evaluation

Success Metrics

Quantified Benefits (Real Case Studies)

• Databricks: 40,000 lines Jsonnet managing hundreds of thousands of YAML files
• Typical team: 50 services, 3-second CI compilation time, 90% reduction in config maintenance
• Developer productivity: 30 seconds to add new service vs 30 minutes manual YAML editing

ROI Calculation

Time Investment: 2-3 weeks learning + 1 week setup
Payoff Threshold: 15+ services with regular configuration changes
Break-even: When YAML copy-paste time exceeds Jsonnet learning investment

Security Considerations

Secret Management: Never embed secrets in Jsonnet files
Recommended Pattern:

{
  env: [{
    name: 'DATABASE_PASSWORD',
    valueFrom: { 
      secretKeyRef: { name: 'db-secrets', key: 'password' }
    }
  }]
}

Integration: Use Kubernetes secrets, external secret operators, or HashiCorp Vault for runtime secret injection.