Maison/arti-api/auth-service/pipeline/JSONNET-GUIDE.md

Drone CI Jsonnet Configuration Guide

✅ Jsonnet is Now Enabled!

Your Drone CI server now supports Jsonnet configurations with the following setup:

🔧 Server Configuration

The following environment variables have been added to enable Jsonnet:

DRONE_JSONNET_ENABLED: "true"
DRONE_STARLARK_ENABLED: "true"  # Bonus: Starlark support too

📁 File Structure

├── .drone.jsonnet           # Main pipeline configuration
├── common.libsonnet         # Shared steps and environment
├── build-steps.libsonnet    # Build-specific logic
├── .drone.yml.backup        # Original YAML (backup)
└── drone-configmap-updated.yaml  # Updated server config

🚀 How to Use Jsonnet

1. Main Configuration (.drone.jsonnet)

• Entry point for your pipeline
• Imports and combines modules
• Generates final pipeline configuration

2. Common Module (common.libsonnet)

• Shared environment variables
• Common steps (clone, test, cleanup)
• Reusable triggers and conditions

3. Build Module (build-steps.libsonnet)

• Build-specific logic
• External Buildah integration
• Container build steps

🔄 Workflow

1. Edit Jsonnet files (.drone.jsonnet, *.libsonnet)
2. Test locally (optional): jsonnet .drone.jsonnet
3. Commit and push - Drone automatically processes Jsonnet
4. Pipeline runs using generated configuration

🛠️ Local Development

Generate YAML for testing:

# Generate YAML from Jsonnet
jsonnet .drone.jsonnet > .drone.yml.test

# Validate generated YAML
python3 -c "import yaml; yaml.safe_load(open('.drone.yml.test'))"

# Compare with original
diff .drone.yml.backup .drone.yml.test

Jsonnet Utilities:

# Format Jsonnet files
jsonnetfmt -i .drone.jsonnet common.libsonnet build-steps.libsonnet

# Validate syntax
jsonnet .drone.jsonnet > /dev/null && echo "✅ Valid Jsonnet"

🎯 Benefits Achieved

Modularity

• ✅ Separate concerns (common vs build-specific)
• ✅ Reusable components
• ✅ Easier maintenance

Flexibility

• ✅ Variables and functions
• ✅ Conditional logic
• ✅ Dynamic configuration

DRY Principle

• ✅ No code duplication
• ✅ Single source of truth
• ✅ Consistent patterns

📋 Configuration Examples

Creating Environment-Specific Builds:

// .drone.jsonnet
local buildSteps = import 'build-steps.libsonnet';
local commonConfig = import 'common.libsonnet';

local environment = std.extVar('environment');

{
  kind: "pipeline",
  type: "kubernetes",
  name: "auth-service-" + environment,
  service_account: "drone-runner",
  environment: commonConfig.environment + {
    BUILD_ENV: environment
  },
  steps: [
    commonConfig.cloneStep,
    commonConfig.testStep,
    buildSteps.externalBuildahStep + {
      commands: [
        // Add environment-specific commands
        "echo 'Building for: " + environment + "'",
      ] + buildSteps.externalBuildahStep.commands
    }
  ]
}

Adding Conditional Steps:

// build-steps.libsonnet
{
  externalBuildahStep: {
    // ... existing configuration
    commands: [
      // ... existing commands
    ] + (
      if std.extVar('push_to_registry') == 'true' then [
        "echo '📤 Pushing to registry...'",
        "kubectl exec $BUILDAH_POD -- buildah push auth-service:1.0.${DRONE_BUILD_NUMBER} docker://registry.aipice.local/auth-service:1.0.${DRONE_BUILD_NUMBER}"
      ] else []
    )
  }
}

🔍 Troubleshooting

Check if Jsonnet is enabled:

kubectl get configmap drone -n apps--droneio--prd -o yaml | grep JSONNET

Verify Drone server restart:

kubectl get pods -n apps--droneio--prd | grep droneio

Test Jsonnet syntax:

jsonnet .drone.jsonnet | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin)"

View generated pipeline in Drone UI:

• Go to your repository in Drone UI
• The generated YAML will be shown in the build view

🎉 Next Steps

1. Create variants: Development, staging, production configurations
2. Add functions: Custom build logic, notification steps
3. Share modules: Reuse across multiple repositories
4. Optimize: Use Jsonnet's advanced features for complex scenarios

Your Drone CI is now supercharged with Jsonnet! 🚀