Kibo Config Xformer

A Node.js runtime configuration loader for Spring Cloud Config Server with lazy property substitution and template processing.

This tool is a Node.js replacement for the .NET Mozu.Core.ConfigXformer.Program CLI, providing the same functionality for loading configuration from Spring Cloud Config Server and transforming template files with property substitution.

Features

• 🔌 Spring Cloud Config Integration: Connects to Spring Cloud Config Server to fetch configuration
• 🔄 Environment Variable Loading: Loads environment variables with .NET style __ to : conversion
• 🎯 Lazy Property Substitution: Recursively resolves ${property.name} placeholders in values
• 📝 Template Processing: Finds and transforms template files with property substitution
• 📤 Multiple Output Formats: Export as bash exports, JSON, YAML, .env, or Kubernetes ConfigMap
• 🔒 Case-Insensitive Keys: Follows .NET convention for case-insensitive configuration keys

Installation

Global Installation (CLI)

npm install -g kibo-config-xformer

Local Installation (Library)

npm install kibo-config-xformer

Environment Variables

The tool reads the following environment variables (using .NET convention where __ is converted to :):

| Environment Variable | Description | Default | |---------------------|-------------|---------| | spring__cloud__config__uri | Spring Cloud Config Server URL | Required | | spring__cloud__config__label | Git branch/label to use | null | | spring__cloud__config__timeout | Request timeout in milliseconds | 15000 | | Mozu__appSettings__environment | Environment/profile name | default | | Mozu__appSettings__scaleUnitId | Scale unit identifier | - |

Example Environment Variables

export spring__cloud__config__uri="http://shared.kube-int.mozu.com/kibo.config"
export spring__cloud__config__label="environment(_)prod"
export Mozu__appSettings__environment="prod"
export Mozu__appSettings__scaleUnitId="tp2"

CLI Usage

Basic Usage

# Load config and output as JSON
kiboConfigXformer

# Load config and output as bash exports (for sourcing)
kiboConfigXformer -x

# Source exports directly
source <(kiboConfigXformer -x)

Template Processing

# Process all *.config_template files in a directory
kiboConfigXformer -d /path/to/configs -e config_template

# Process with custom regex pattern
kiboConfigXformer -d /path/to/configs -e template -r '\$\{([^}]+)\}'

Output Formats

# Output as JSON file
kiboConfigXformer -o config.json --format json

# Output as YAML file
kiboConfigXformer -o config.yaml --format yaml

# Output as .env file
kiboConfigXformer -o .env --format env

# Output as Kubernetes ConfigMap
kiboConfigXformer -k -o configmap.yaml --name my-app --namespace production

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -x, --export-list | Output bash export statements to stdout | - | | -p, --escaping <char> | Character to use for escaping in env var names | _ | | -d, --dir <directory> | Directory to search for template files | - | | -o, --out <file> | Output file path | - | | -k, --kube | Output as Kubernetes ConfigMap | - | | -e, --ext <extension> | Template file extension to search for | config_template | | -r, --regex <pattern> | Regex pattern for property placeholders | \$\{([^}]+)\} | | --name <name> | ConfigMap name (for -k) | app-config | | --namespace <namespace> | Kubernetes namespace (for -k) | default | | --format <format> | Output format: json, yaml, env, exports | json |

Property Substitution

The tool supports lazy property substitution with ${property.name} syntax. Properties can reference other properties, and resolution happens recursively.

Example

Given configuration:

{
  "mozu:appSettings:rabbit_default_username": "admin",
  "mozu:appSettings:rabbit_default_password": "secret",
  "mozu:appSettings:rabbit_hp_host": "rabbitmq.example.com",
  "EventNotificationListenerHomePodMessageQueue": "rabbitmq://${mozu.appSettings.rabbit_default_username}:${mozu.appSettings.rabbit_default_password}@${mozu.appSettings.rabbit_hp_host}/Mozu_Dev_Event_EventListener?ha=true&heartbeat=30"
}

The EventNotificationListenerHomePodMessageQueue value will be resolved to:

rabbitmq://admin:[email protected]/Mozu_Dev_Event_EventListener?ha=true&heartbeat=30

Key Formats

Both dot notation and colon notation work:

• ${mozu.appSettings.rabbit_default_username}
• ${mozu:appSettings:rabbit_default_username}

Both are equivalent and will be normalized to colon notation internally.

Template File Processing

Template files are processed by finding all files with the specified extension, resolving property placeholders, and writing output files with the template extension removed.

Example

Input file: appsettings.config_template

{
  "database": {
    "host": "${database:host}",
    "port": "${database:port}",
    "connectionString": "mongodb://${database:host}:${database:port}/mydb"
  }
}

After processing:

• Output file: appsettings.config
• All ${...} placeholders replaced with actual values from configuration

Programmatic Usage

const { KiboConfigXformer } = require('kibo-config-xformer');

async function loadConfig() {
  const xformer = new KiboConfigXformer();

  // Load and resolve all configuration
  const config = await xformer.loadConfig();

  console.log('Resolved config:', config);

  // Access individual components
  const {
    configLoader,
    propertyResolver,
    templateProcessor,
    outputFormatter
  } = xformer.getComponents();

  // Process templates programmatically
  await templateProcessor.processTemplateDirectory('/path/to/templates', 'config_template');

  // Format output
  const bashExports = outputFormatter.formatAsExports(config);
  console.log(bashExports);
}

loadConfig().catch(console.error);

How It Works

1. Load Environment Variables: Reads all environment variables and converts __ to : for .NET compatibility
2. Fetch Spring Cloud Config: Makes HTTP request to Spring Cloud Config Server with application name, profile, and label
3. Merge Configuration: Combines environment variables and Spring Cloud Config properties (environment variables take precedence)
4. Lazy Resolution: Resolves ${...} placeholders recursively when properties are accessed
5. Template Processing: (Optional) Finds template files, resolves placeholders, and writes output files
6. Output Formatting: Formats configuration in requested format (bash exports, JSON, YAML, .env, Kubernetes ConfigMap)

Comparison with .NET ConfigXformer

This Node.js implementation provides feature parity with the original .NET Mozu.Core.ConfigXformer.Program:

| Feature | .NET ConfigXformer | Node.js ConfigXformer | |---------|-------------------|---------------------| | Spring Cloud Config | ✅ (via Steeltoe) | ✅ (via cloud-config-client) | | Environment Variable Loading | ✅ (__ to :) | ✅ (__ to :) | | Property Substitution | ✅ (${...}) | ✅ (${...}) | | Template Processing | ✅ | ✅ | | Bash Exports | ✅ (-x) | ✅ (-x) | | Kubernetes ConfigMap | ✅ (-k) | ✅ (-k) | | Raw Output | ✅ (-o) | ✅ (-o) | | Custom Regex | ✅ (-r) | ✅ (-r) |

Examples

Example 1: Load and Source Configuration

# Set environment variables
export spring__cloud__config__uri="http://config-server:8888"
export Mozu__appSettings__environment="production"

# Load config and export to environment
source <(kiboConfigXformer -x)

# Now all config properties are available as environment variables
echo $DATABASE_HOST

Example 2: Process Template Files

# Process all *.config_template files in config directory
kiboConfigXformer -d ./config -e config_template

# This will:
# - Find all *.config_template files recursively
# - Resolve ${...} placeholders in each file
# - Write output files with .config_template removed

Example 3: Generate Kubernetes ConfigMap

# Generate ConfigMap for production namespace
kiboConfigXformer -k -o k8s-configmap.yaml --name my-app-config --namespace production

# Apply to Kubernetes
kubectl apply -f k8s-configmap.yaml

Error Handling

The tool includes comprehensive error handling:

• Connection Errors: Timeout and retry logic for Spring Cloud Config Server
• Circular Dependencies: Detects circular property references
• Missing Placeholders: Warns about unresolved placeholders but continues processing
• File Errors: Reports template processing failures without stopping batch operations

Enable debug mode for detailed error information:

DEBUG=1 kiboConfigXformer -x

License

ISC

Contributing

Contributions welcome! Please open an issue or submit a pull request.