SousChef: Multi-Platform to Ansible Migration + Ansible Upgrade Planning

Transform Chef, SaltStack, Puppet, PowerShell, and Bash automation to Ansible, and plan Ansible version upgrades. Works with any AI assistant via MCP (Model Context Protocol)—Claude, GPT-4, GitHub Copilot, Red Hat AI, local models, and more.

Quick Facts: MIT License | Python 3.10+ | 95 MCP Tools | 91% Test Coverage

The optional web UI and Pillow-dependent development packages require Python 3.11+. Core MCP server support remains Python 3.10+.

Warning I did not hand craft 100k lines of code in two days while doing my actual day job (which, for the record, isn’t this). A lot of this is AI generated. Architected, hand edited, and personally sworn at yes, but the heavy hand of AI is all over this repo.

I’ve pushed it to include a lot of tests, and I run it through its paces before pushing, but some things may break, or may have always been broken. If you find something, raise it and I’ll fix it.

A fair bit of this relies on mocked Chef/AWX/AAP APIs because shockingly I don’t have a fleet of enterprise grade installs with enterprise grade data sitting around to test against. Buyer beware (doubly so, since you didn’t actually buy anything).

What It Does

Chef-to-Ansible Migration — Convert cookbooks, recipes, custom resources, data bags, and Habitat plans to Ansible playbooks, roles, and containers. Supports infrastructure, applications, and day-2 operations.

SaltStack-to-Ansible Migration — Convert Salt states, pillars, and top.sls targeting to Ansible roles, variable files, Ansible Vault, and INI inventory. Assess complexity, generate phased migration plans, and produce executive reports.

Puppet to Ansible Migration — Convert Puppet manifests and module directories to Ansible playbooks using idiomatic ansible.builtin modules. Recognises 14 Puppet resource types; maps 10 to Ansible modules with AI-assisted conversion for complex constructs.

PowerShell to Ansible Migration — Convert Windows PowerShell provisioning scripts to idiomatic ansible.windows playbooks, roles, WinRM inventories, and AWX/AAP job templates.

Bash Script Migration — Convert provisioning Bash scripts to Ansible playbooks and roles with quality scoring, sensitive data detection, and AAP readiness hints.

Ansible Upgrade Planning — Assess compatibility, plan version upgrades, validate collections, identify breaking changes, and generate testing strategies.

Installation & Setup

# Install from PyPI
pip install mcp-souschef

# Configure your MCP client (Claude Desktop example)
cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart your AI assistant and start using
# Ask: "What migration tools are available?"

Other MCP clients: See config/CONFIGURATION.md for VS Code Copilot, custom setups, and Docker deployment.

Production containers use isolated, wheel-only dependencies and omit pip and Poetry. Rebuild images to change dependencies; see the container dependency policy.

Key Features

• 95 MCP tools for Chef migration, SaltStack migration, Puppet migration, PowerShell migration, Bash script migration, and Ansible upgrades
• Web UI with interactive migration planner and visualisation (including Salt, Puppet, PowerShell, and Bash tabs)
• CLI for automation and CI/CD integration
• Production-ready with 91% test coverage and comprehensive validation
• Model-agnostic — works with any AI assistant supporting MCP
• Chef Server ingestion with dependency closure and offline bundle export

Common Use Cases

Chef Migration:

• Convert cookbooks to Ansible playbooks and roles
• Migrate Chef Habitat apps to Docker containers
• Transform data bags to Ansible Vault
• Generate AWX/AAP job templates and workflows
• Convert InSpec tests to Ansible validation tasks
• Fetch cookbooks from Chef Server with run_list or policy selection

SaltStack Migration:

• Parse SLS state files and extract states, pillars, and grain references
• Convert Salt states to Ansible playbooks and role task files
• Migrate pillar data to Ansible group_vars/ and Ansible Vault
• Generate Ansible inventory from top.sls targeting rules
• Batch-convert a full Salt state tree to an Ansible roles structure
• Assess migration complexity and generate phased migration plans

Puppet Migration:

• Convert Puppet manifests (.pp) and module directories to Ansible playbooks
• Recognise 14 Puppet resource types; map 10 to idiomatic ansible.builtin modules (package, service, file, user, group, exec, cron, host, mount, ssh_authorized_key)
• Warn about unsupported constructs (Hiera lookups, exported resources, create_resources) with manual-review guidance
• AI-assisted conversion for complex Puppet DSL that cannot be mapped automatically
• Convert individual Puppet resource declarations to standalone Ansible tasks

PowerShell Migration:

• Convert Windows PowerShell provisioning scripts to idiomatic Ansible playbooks
• Generate full Ansible roles with WinRM inventory and group_vars
• Map 28+ PowerShell patterns to ansible.windows.*, community.windows.*, chocolatey.chocolatey.*
• Generate AWX/AAP Windows job templates with WinRM credentials
• Analyse migration fidelity (0–100 %) with actionable recommendations
• Create complete requirements.yml for required Windows collections

Bash Script Migration:

• Convert provisioning Bash scripts to idiomatic Ansible playbooks
• Generate full Ansible roles from Bash scripts (tasks, handlers, defaults, meta)
• Detect and flag hardcoded secrets with ansible-vault guidance
• Identify CM escape calls (Salt, Puppet, Chef) embedded in Bash
• Get AAP-ready job template hints with Execution Environment recommendations
• Score migration quality (A–F) with ranked improvement suggestions

Ansible Upgrades:

• Assess Python and Ansible version compatibility
• Plan upgrades with breaking change analysis
• Validate collection compatibility
• Generate testing strategies
• Track end-of-life dates

Both Infrastructure & Applications:

• Infrastructure provisioning and configuration
• Application deployment automation
• Day-2 operations (backups, scaling, updates)
• CI/CD pipeline migration
• Multi-cloud automation

Command-Line Examples

# Chef migration
souschef-cli recipe /path/to/recipe.rb
souschef-cli template /path/to/template.erb
souschef-cli convert package nginx --action install

# SaltStack migration
souschef-cli salt assess /srv/salt/states/
souschef-cli salt convert /srv/salt/states/webserver/init.sls
souschef-cli salt inventory /srv/salt/top.sls
souschef-cli salt batch-convert /srv/salt/states/ --output-dir ./ansible-roles/

# PowerShell migration
souschef-cli powershell-parse scripts/setup.ps1
souschef-cli powershell-convert scripts/setup.ps1 --output playbook.yml
souschef-cli powershell-role scripts/setup.ps1 --output-dir ./ansible-role

# Puppet migration
souschef-cli puppet parse manifests/site.pp
souschef-cli puppet convert manifests/site.pp --output playbook.yml
souschef-cli puppet convert-module modules/myapp --output-dir ./ansible-role

# Bash script migration
souschef bash parse scripts/bootstrap.sh
souschef bash convert scripts/deploy.sh --output playbook.yml
souschef bash role scripts/setup.sh --role-name myapp --output-dir ./roles

# Ansible upgrades
souschef ansible assess --environment-path /path/to/ansible
souschef ansible plan --current 2.9 --target 2.17
souschef ansible validate-collections --requirements-file requirements.yml

# Web UI
souschef ui  # Launch interactive dashboard

REST API v1 (Migration Workflow)

SousChef includes a lightweight HTTP API for programmatic execution.

# List generic operation names
curl -s http://127.0.0.1:8081/api/v1/operations

# Analyse migration complexity (dedicated endpoint)
curl -s -X POST http://127.0.0.1:8081/api/v1/migration/analyse \
 -H "Content-Type: application/json" \
 -d '{
  "cookbook_paths": ["/workspaces/souschef/tests/integration/fixtures/sample_cookbook"],
  "migration_scope": "full",
  "target_platform": "ansible_awx"
 }'

# Generate playbook from a recipe (dedicated endpoint)
curl -s -X POST http://127.0.0.1:8081/api/v1/migration/generate-playbook \
 -H "Content-Type: application/json" \
 -d '{
  "recipe_path": "/workspaces/souschef/tests/integration/fixtures/sample_cookbook/recipes/default.rb",
  "cookbook_path": "/workspaces/souschef/tests/integration/fixtures/sample_cookbook"
 }'

# Generate migration plan (dedicated endpoint)
curl -s -X POST http://127.0.0.1:8081/api/v1/migration/plan \
 -H "Content-Type: application/json" \
 -d '{
  "cookbook_paths": ["/workspaces/souschef/tests/integration/fixtures/sample_cookbook"],
  "migration_strategy": "phased",
  "timeline_weeks": 12
 }'

# Validate conversion output with profile-based filtering
curl -s -X POST http://127.0.0.1:8081/api/v1/validation/profile \
 -H "Content-Type: application/json" \
 -d '{
  "conversion_type": "recipe",
  "result_content": "- hosts: all\n  tasks: []",
  "validation_profile": "moderate"
 }'

# Query migration capability context (keyword, vector, or hybrid retrieval)
curl -s -X POST http://127.0.0.1:8081/api/v1/context/query \
 -H "Content-Type: application/json" \
 -d '{
  "query": "migration plan timeline",
  "top_k": 5,
  "cookbook_path": "/workspaces/souschef/tests/integration/fixtures/sample_cookbook",
  "retrieval_mode": "hybrid"
 }'

# Stream context matches as server-sent events
curl -N -X POST http://127.0.0.1:8081/api/v1/context/query/stream \
 -H "Content-Type: application/json" \
 -d '{
  "query": "migration plan timeline",
  "top_k": 3
 }'

# Stream validation profile results as server-sent events
curl -N -X POST http://127.0.0.1:8081/api/v1/validation/profile/stream \
 -H "Content-Type: application/json" \
 -d '{
  "conversion_type": "recipe",
  "result_content": "- hosts: all\n  tasks: []",
  "validation_profile": "safety"
 }'

Request guardrails: per-route payload limits return 413, and operation timeouts return 408. Route resolution occurs before payload validation, so unknown routes return 404 even when a body would exceed endpoint payload limits.

Start the API server from the CLI:

souschef api serve --host 127.0.0.1 --port 8081

Validation profiles: basic, moderate, safety, shared, production.

Documentation

Start Here

• Quick Start Guide — Get running in 5 minutes
• Production Safety — Validate migrations before deploying ⚠️
• User Guide — All 95 tools explained with examples
• Chef Migration Guide — Step-by-step Chef-to-Ansible migration process
• Salt Migration Guide — Step-by-step SaltStack-to-Ansible migration process
• Bash Migration Guide — Step-by-step Bash provisioning script migration process
• Puppet Migration Guide — Puppet to Ansible conversion
• PowerShell Migration Guide — PowerShell to Windows Ansible conversion
• Ansible Upgrades — Version upgrade planning workflows

Reference

• API Documentation — Complete technical reference
• Architecture Guide — Code structure and design decisions
• Contributing Guide — Development standards and workflow
• Security Policy — Vulnerability reporting and security features
• Changelog — Complete release history

Recent Updates

v7.0.0 — First-class multi-platform migration documentation for SaltStack, Bash, PowerShell, and Puppet

v6.0.0 — v2 core foundation with enhanced migration capabilities

v5.1.4 — Modular architecture, 91% test coverage, full type safety, production-ready

v5.0.0 — Complete Ansible upgrade planning with version matrices and EOL tracking

Contributing

# Development setup
git clone https://github.com/kpeacocke/souschef.git && cd souschef
poetry install
poetry run pytest           # Run tests
poetry run ruff check .     # Lint
poetry run mypy souschef    # Type check

# If you change terraform-provider/
cd terraform-provider
go test ./...               # Run Go tests

Standards: Zero warnings policy, type hints required, 90%+ test coverage, Australian English spelling.

See CONTRIBUTING.md for complete guidelines.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md

License

MIT License — see LICENSE for details.