provisioning/docs/src/infrastructure/infrastructure-from-code-guide.md

Infrastructure-from-Code (IaC) Guide

Overview

The Infrastructure-from-Code system automatically detects technologies in your project and infers infrastructure requirements based on organization-specific rules. It consists of three main commands:

• detect: Scan a project and identify technologies
• complete: Analyze gaps and recommend infrastructure components
• ifc: Full-pipeline orchestration (workflow)

Quick Start

1. Detect Technologies in Your Project

Scan a project directory for detected technologies:

provisioning detect /path/to/project --out json

Output Example:

{
  "detections": [
    {"technology": "nodejs", "confidence": 0.95},
    {"technology": "postgres", "confidence": 0.92}
  ],
  "overall_confidence": 0.93
}

2. Analyze Infrastructure Gaps

Get a completeness assessment and recommendations:

provisioning complete /path/to/project --out json

Output Example:

{
  "completeness": 1.0,
  "changes_needed": 2,
  "is_safe": true,
  "change_summary": "+ Adding: postgres-backup, pg-monitoring"
}

3. Run Full Workflow

Orchestrate detection → completion → assessment pipeline:

provisioning ifc /path/to/project --org default

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 Infrastructure-from-Code Workflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 1: Technology Detection
────────────────────────────
✓ Detected 2 technologies

STEP 2: Infrastructure Completion
─────────────────────────────────
✓ Completeness: 1%

✅ Workflow Complete

Command Reference

detect

Scan and detect technologies in a project.

Usage:

provisioning detect [PATH] [OPTIONS]

Arguments:

• PATH: Project directory to analyze (default: current directory)

Options:

• -o, --out TEXT: Output format - text, json, yaml (default: text)
• -C, --high-confidence-only: Only show detections with confidence > 0.8
• --pretty: Pretty-print JSON/YAML output
• -x, --debug: Enable debug output

Examples:

# Detect with default text output
provisioning detect /path/to/project

# Get JSON output for parsing
provisioning detect /path/to/project --out json | jq '.detections'

# Show only high-confidence detections
provisioning detect /path/to/project --high-confidence-only

# Pretty-printed YAML output
provisioning detect /path/to/project --out yaml --pretty

complete

Analyze infrastructure completeness and recommend changes.

Usage:

provisioning complete [PATH] [OPTIONS]

Arguments:

• PATH: Project directory to analyze (default: current directory)

Options:

• -o, --out TEXT: Output format - text, json, yaml (default: text)
• -c, --check: Check mode (report only, no changes)
• --pretty: Pretty-print JSON/YAML output
• -x, --debug: Enable debug output

Examples:

# Analyze completeness
provisioning complete /path/to/project

# Get detailed JSON report
provisioning complete /path/to/project --out json

# Check mode (dry-run, no changes)
provisioning complete /path/to/project --check

ifc (workflow)

Run the full Infrastructure-from-Code pipeline.

Usage:

provisioning ifc [PATH] [OPTIONS]

Arguments:

• PATH: Project directory to process (default: current directory)

Options:

• --org TEXT: Organization name for rule loading (default: default)
• -o, --out TEXT: Output format - text, json (default: text)
• --apply: Apply recommendations (future feature)
• -v, --verbose: Verbose output with timing
• --pretty: Pretty-print output
• -x, --debug: Enable debug output

Examples:

# Run workflow with default rules
provisioning ifc /path/to/project

# Run with organization-specific rules
provisioning ifc /path/to/project --org acme-corp

# Verbose output with timing
provisioning ifc /path/to/project --verbose

# JSON output for automation
provisioning ifc /path/to/project --out json

Organization-Specific Inference Rules

Customize how infrastructure is inferred for your organization.

Understanding Inference Rules

An inference rule tells the system: "If we detect technology X, we should recommend taskservice Y."

Rule Structure:

version: "1.0.0"
organization: "your-org"
rules:
  - name: "rule-name"
    technology: ["detected-tech"]
    infers: "required-taskserv"
    confidence: 0.85
    reason: "Why this taskserv is needed"
    required: true

Creating Custom Rules

Create an organization-specific rules file:

# ACME Corporation rules
cat > $PROVISIONING/config/inference-rules/acme-corp.yaml << 'EOF'
version: "1.0.0"
organization: "acme-corp"
description: "ACME Corporation infrastructure standards"

rules:
  - name: "nodejs-to-redis"
    technology: ["nodejs", "express"]
    infers: "redis"
    confidence: 0.85
    reason: "Node.js applications need caching"
    required: false

  - name: "postgres-to-backup"
    technology: ["postgres"]
    infers: "postgres-backup"
    confidence: 0.95
    reason: "All databases require backup strategy"
    required: true

  - name: "all-services-monitoring"
    technology: ["nodejs", "python", "postgres"]
    infers: "monitoring"
    confidence: 0.90
    reason: "ACME requires monitoring on production services"
    required: true
EOF

Then use them:

provisioning ifc /path/to/project --org acme-corp

Default Rules

If no organization rules are found, the system uses sensible defaults:

• Node.js + Express → Redis (caching)
• Node.js → Nginx (reverse proxy)
• Database → Backup (data protection)
• Docker → Kubernetes (orchestration)
• Python → Gunicorn (WSGI server)
• PostgreSQL → Monitoring (production safety)

Output Formats

Text Output (Default)

Human-readable format with visual indicators:

STEP 1: Technology Detection
────────────────────────────
✓ Detected 2 technologies

STEP 2: Infrastructure Completion
─────────────────────────────────
✓ Completeness: 1%

JSON Output

Structured format for automation and parsing:

provisioning detect /path/to/project --out json | jq '.detections[0]'

Output:

{
  "technology": "nodejs",
  "confidence": 0.8333333134651184,
  "evidence_count": 1
}

YAML Output

Alternative structured format:

provisioning detect /path/to/project --out yaml

Practical Examples

Example 1: Node.js + PostgreSQL Project

# Step 1: Detect
$ provisioning detect my-app
✓ Detected: nodejs, express, postgres, docker

# Step 2: Complete
$ provisioning complete my-app
✓ Changes needed: 3
  - redis (caching)
  - nginx (reverse proxy)
  - pg-backup (database backup)

# Step 3: Full workflow
$ provisioning ifc my-app --org acme-corp

Example 2: Python Django Project

$ provisioning detect django-app --out json
{
  "detections": [
    {"technology": "python", "confidence": 0.95},
    {"technology": "django", "confidence": 0.92}
  ]
}

# Inferred requirements (with gunicorn, monitoring, backup)

Example 3: Microservices Architecture

$ provisioning ifc microservices/ --org mycompany --verbose
🔍 Processing microservices/
  - service-a: nodejs + postgres
  - service-b: python + redis
  - service-c: go + mongodb

✓ Detected common patterns
✓ Applied 12 inference rules
✓ Generated deployment plan

Integration with Automation

CI/CD Pipeline Example

#!/bin/bash
# Check infrastructure completeness in CI/CD

PROJECT_PATH=${1:-.}
COMPLETENESS=$(provisioning complete $PROJECT_PATH --out json | jq '.completeness')

if (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then
    echo "❌ Infrastructure completeness too low: $COMPLETENESS"
    exit 1
fi

echo "✅ Infrastructure is complete: $COMPLETENESS"

Configuration as Code Integration

# Generate JSON for infrastructure config
provisioning detect /path/to/project --out json > infra-report.json

# Use in your config processing
cat infra-report.json | jq '.detections[]' | while read -r tech; do
    echo "Processing technology: $tech"
done

Troubleshooting

"Detector binary not found"

Solution: Ensure the provisioning project is properly built:

cd $PROVISIONING/platform
cargo build --release --bin provisioning-detector

No technologies detected

Check:

1. Project path is correct: provisioning detect /actual/path
2. Project contains recognizable technologies (package.json, Dockerfile, requirements.txt, etc.)
3. Use --debug flag for more details: provisioning detect /path --debug

Organization rules not being applied

Check:

1. Rules file exists: $PROVISIONING/config/inference-rules/{org}.yaml
2. Organization name is correct: provisioning ifc /path --org myorg
3. Verify rules structure with: cat $PROVISIONING/config/inference-rules/myorg.yaml

Advanced Usage

Custom Rule Template

Generate a template for a new organization:

# Template will be created with proper structure
provisioning rules create --org neworg

Validate Rule Files

# Check for syntax errors
provisioning rules validate /path/to/rules.yaml

Export Rules for Integration

Export as Rust code for embedding:

provisioning rules export myorg --format rust > rules.rs

Best Practices

1. Organize by Organization: Keep separate rules for different organizations
2. High Confidence First: Start with rules you're confident about (confidence > 0.8)
3. Document Reasons: Always fill in the reason field for maintainability
4. Test Locally: Run on sample projects before applying organization-wide
5. Version Control: Commit inference rules to version control
6. Review Changes: Always inspect recommendations with --check first

Related Commands

# View available taskservs that can be inferred
provisioning taskserv list

# Create inferred infrastructure
provisioning taskserv create {inferred-name}

# View current configuration
provisioning env | grep PROVISIONING

Support and Documentation

• Full CLI Help: provisioning help
• Specific Command Help: provisioning help detect
• Configuration Guide: See CONFIG_ENCRYPTION_GUIDE.md
• Task Services: See SERVICE_MANAGEMENT_GUIDE.md

---

Quick Reference

3-Step Workflow

# 1. Detect technologies
provisioning detect /path/to/project

# 2. Analyze infrastructure gaps
provisioning complete /path/to/project

# 3. Run full workflow (detect + complete)
provisioning ifc /path/to/project --org myorg

Common Commands

Task	Command
Detect technologies	provisioning detect /path
Get JSON output	provisioning detect /path --out json
Check completeness	provisioning complete /path
Dry-run (check mode)	provisioning complete /path --check
Full workflow	provisioning ifc /path --org myorg
Verbose output	provisioning ifc /path --verbose
Debug mode	provisioning detect /path --debug

Output Formats

# Text (human-readable)
provisioning detect /path --out text

# JSON (for automation)
provisioning detect /path --out json | jq '.detections'

# YAML (for configuration)
provisioning detect /path --out yaml

Organization Rules

Use Organization Rules

provisioning ifc /path --org acme-corp

Create Rules File

mkdir -p $PROVISIONING/config/inference-rules
cat > $PROVISIONING/config/inference-rules/myorg.yaml << 'EOF'
version: "1.0.0"
organization: "myorg"
rules:
  - name: "nodejs-to-redis"
    technology: ["nodejs"]
    infers: "redis"
    confidence: 0.85
    reason: "Caching layer"
    required: false
EOF

Example: Node.js + PostgreSQL

$ provisioning detect myapp
✓ Detected: nodejs, postgres

$ provisioning complete myapp
✓ Changes: +redis, +nginx, +pg-backup

$ provisioning ifc myapp --org default
✓ Detection: 2 technologies
✓ Completion: recommended changes
✅ Workflow complete

CI/CD Integration

#!/bin/bash
# Check infrastructure is complete before deploy
COMPLETENESS=$(provisioning complete . --out json | jq '.completeness')

if (( $(echo "$COMPLETENESS < 0.9" | bc -l) )); then
    echo "Infrastructure incomplete: $COMPLETENESS"
    exit 1
fi

JSON Output Examples

Detect Output

{
  "detections": [
    {"technology": "nodejs", "confidence": 0.95},
    {"technology": "postgres", "confidence": 0.92}
  ],
  "overall_confidence": 0.93
}

Complete Output

{
  "completeness": 1.0,
  "changes_needed": 2,
  "is_safe": true,
  "change_summary": "+ redis, + monitoring"
}

Flag Reference

Flag	Short	Purpose
--out TEXT	-o	Output format: text, json, yaml
--debug	-x	Enable debug output
--pretty		Pretty-print JSON/YAML
--check	-c	Dry-run (detect/complete)
--org TEXT		Organization name (ifc)
--verbose	-v	Verbose output (ifc)
--apply		Apply changes (ifc, future)

Troubleshooting

Issue	Solution
"Detector binary not found"	cd $PROVISIONING/platform && cargo build --release
No technologies detected	Check file types (.py, .js, go.mod, package.json, etc.)
Organization rules not found	Verify file exists: $PROVISIONING/config/inference-rules/{org}.yaml
Invalid path error	Use absolute path: provisioning detect /full/path

Environment Variables

Variable	Purpose
$PROVISIONING	Path to provisioning root
$PROVISIONING_ORG	Default organization (optional)

Default Inference Rules

• Node.js + Express → Redis (caching)
• Node.js → Nginx (reverse proxy)
• Database → Backup (data protection)
• Docker → Kubernetes (orchestration)
• Python → Gunicorn (WSGI)
• PostgreSQL → Monitoring (production)

Useful Aliases

# Add to shell config
alias detect='provisioning detect'
alias complete='provisioning complete'
alias ifc='provisioning ifc'

# Usage
detect /my/project
complete /my/project
ifc /my/project --org myorg

Tips & Tricks

Parse JSON in bash:

provisioning detect . --out json | \
  jq '.detections[] | .technology' | \
  sort | uniq

Watch for changes:

watch -n 5 'provisioning complete . --out json | jq ".completeness"'

Generate reports:

provisioning detect . --out yaml > detection-report.yaml
provisioning complete . --out yaml > completion-report.yaml

Validate all organizations:

for org in $PROVISIONING/config/inference-rules/*.yaml; do
    org_name=$(basename "$org" .yaml)
    echo "Testing $org_name..."
    provisioning ifc . --org "$org_name" --check
done

Related Guides

• Full guide: docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md
• Inference rules: docs/user/INFRASTRUCTURE_FROM_CODE_GUIDE.md#organization-specific-inference-rules
• Service management: docs/user/SERVICE_MANAGEMENT_QUICKREF.md
• Configuration: docs/user/CONFIG_ENCRYPTION_QUICKREF.md