Skip to content

Quick Start Guide#

Get up and running with SousChef in minutes. This guide walks you through your first Chef-to-Ansible migration.

Prerequisites#

Before you begin, make sure you have:

  • SousChef installed (Installation guide)
  • MCP client configured (choose one below)
  • A Chef cookbook to migrate

MCP Client Setup#

Choose your preferred AI assistant and follow the setup instructions:

1. Install SousChef: 

pip install mcp-souschef

2. Configure Claude Desktop:

cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

cp config/claude-desktop.json ~/.config/Claude/claude_desktop_config.json

copy config\claude-desktop.json %APPDATA%\Claude\claude_desktop_config.json

3. Restart Claude Desktop

4. Verify: Open Claude and ask "What Chef migration tools are available?"

MCP Support Available

GitHub Copilot in VS Code supports MCP servers starting from VS Code 1.102 (January 2026).

Prerequisites

  • VS Code 1.102 or later
  • GitHub Copilot extension installed
  • Python 3.10+ installed

Setup Steps

  1. Install SousChef: 

    pip install mcp-souschef

  2. Configure MCP Server:

Copy the configuration to your VS Code user directory:

cp config/vscode-copilot.json ~/.config/Code/User/mcp.json

copy config\vscode-copilot.json %APPDATA%\Code\User\mcp.json

Or create ~/.config/Code/User/mcp.json (macOS/Linux) or %APPDATA%\Code\User\mcp.json (Windows) with: 

{
  "servers": {
    "souschef": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "mcp-souschef", "souschef"]
    }
  }
}

  1. Activate in VS Code:

    • Reload VS Code window (Cmd+Shift+P → "Developer: Reload Window")
    • Run MCP: List Servers from Command Palette
    • Find "souschef" and start it
    • Trust the server when prompted

  2. Start Using:

    • Open GitHub Copilot Chat (Ctrl+Cmd+I or Ctrl+Alt+I)
    • Click the Tools button to enable SousChef tools
    • Start asking questions!

Example Prompts: 

What Chef cookbooks are in /path/to/cookbooks?
Convert this Chef recipe to Ansible
Assess the complexity of migrating cookbook XYZ

Explicit Tool References: 

#list_cookbook_structure /path/to/cookbook
#parse_recipe /path/to/recipe.rb

Learn more about MCP in VS Code →

1. Install SousChef: 

pip install mcp-souschef

2. Add to your MCP client config: 

{
  "mcpServers": {
    "souschef": {
      "command": "uvx",
      "args": ["mcp-souschef"]
    }
  }
}

3. Restart your MCP client

Your First Migration#

Step 1: Analyze a Cookbook#

Start by analyzing a Chef cookbook to understand its structure:

Ask your AI assistant: 

Can you analyze the cookbook at /path/to/cookbook?


souschef-cli cookbook /path/to/cookbook

The analysis will show: - Cookbook structure and files - Recipe resources and actions - Attributes and their precedence - Template variables - Dependencies

Step 2: Convert a Recipe to a Playbook#

Convert your first Chef recipe to an Ansible playbook:

Convert the recipe /path/to/cookbook/recipes/default.rb to an Ansible playbook

souschef-cli recipe /path/to/cookbook/recipes/default.rb > playbook.yml

Example conversion:

Chef Recipe (recipes/webserver.rb): 

package 'nginx' do
  action :install
end

service 'nginx' do
  action [:enable, :start]
end

template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  variables({
    worker_processes: node['nginx']['workers']
  })
  notifies :reload, 'service[nginx]'
end

Generated Ansible Playbook: 

---
- name: Webserver cookbook playbook
  hosts: all
  become: yes

  tasks:
    - name: Install nginx
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Enable and start nginx
      ansible.builtin.service:
        name: nginx
        enabled: yes
        state: started

    - name: Configure nginx
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      vars:
        worker_processes: "{{ nginx_workers }}"
      notify: Reload nginx

  handlers:
    - name: Reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

Step 3: Validate the Conversion#

Validate that the conversion is correct and follows best practices:

Validate the playbook conversion for accuracy and best practices

souschef-cli validate playbook.yml

The validation checks: - [YES] Syntax correctness - [YES] Semantic equivalence - [YES] Best practices compliance - [YES] Security considerations - [YES] Performance optimizations

Step 4: Test the Playbook#

Before deploying, test your converted playbook:

# Syntax check
ansible-playbook playbook.yml --syntax-check

# Dry run
ansible-playbook playbook.yml --check

# Run on test environment
ansible-playbook playbook.yml -i test_inventory

Common Migration Patterns#

Converting Data Bags to Variables#

Convert Chef data bags to Ansible variables:

Convert the data bag /path/to/data_bags/users.json to Ansible variables

Generating AWX Job Templates#

Create AWX/AAP job templates from cookbooks:

Generate an AWX job template from the cookbook at /path/to/cookbook

Converting InSpec Tests#

Convert InSpec tests to Ansible validation:

Convert the InSpec profile /path/to/inspec to Ansible tests

Example Workflows#

Complete Cookbook Migration#

  1. Assess complexity: 

    Assess the migration complexity for /path/to/cookbook

  2. Generate migration plan: 

    Generate a migration plan for this cookbook

  3. Convert recipes: 

    Convert all recipes in this cookbook to playbooks

  4. Convert data bags: 

    Convert data bags to Ansible Vault

  5. Create AWX integration: 

    Generate AWX job templates for this cookbook

Habitat to Container Migration#

  1. Parse Habitat plan: 

    Parse the Habitat plan at /habitat/plan.sh

  2. Convert to Dockerfile: 

    Convert this Habitat plan to a Dockerfile using ubuntu:22.04

  3. Generate Compose: 

    Generate docker-compose.yml for these Habitat plans

Tips for Success#

Start Small

Begin with a simple cookbook that has few dependencies. This helps you understand the conversion process before tackling complex cookbooks.

Review Conversions

Always review generated playbooks for:

  • Correct module selection
  • Proper variable substitution
  • Guard condition conversion
  • Notification handling

Use Validation

Run the validation tool on every conversion to catch potential issues early.

Test Incrementally

Test converted playbooks in a development environment before production deployment.

Next Steps#

Now that you've completed your first migration, explore:

Getting Help#

If you encounter issues:

  1. Check the Troubleshooting section
  2. Review the API Reference
  3. Ask your AI assistant for help
  4. Open an issue on GitHub

Troubleshooting#

Conversion Doesn't Match Expected Output#

  • Review the Chef recipe for complex guards or custom resources
  • Check attribute precedence in the source cookbook
  • Validate that template variables are correctly extracted

Playbook Fails Ansible Lint#

  • Run the validation tool to identify issues
  • Review Ansible best practices in the User Guide
  • Check for deprecated module usage

Performance Issues with Large Cookbooks#

  • Use the profiling tools to identify bottlenecks: 
    souschef-cli profile /path/to/large_cookbook
  • Consider breaking large recipes into smaller, focused playbooks
  • Review the Performance Optimization guide