TL;DR: This tool uses AI to automatically convert Chef cookbooks to Ansible roles. It works with a well-crafted prompt for Claude API that I improved through testing with real examples. The result is good-quality Ansible code with much less manual work.
Moving from Chef to Ansible is hard work that typically requires lots of manual effort and deep knowledge of both systems. I built the Chef to Ansible Converter to make this process much easier for DevOps teams.
The Core Challenge: Translating Between Different IaC Systems
Chef uses Ruby-based DSL while Ansible uses YAML syntax, making them very different systems to work with. Converting Chef cookbooks (with their recipes, attributes, templates, and custom resources) to Ansible roles by hand takes a lot of time and is prone to mistakes. My solution combines careful Chef code parsing with AI language models to handle this translation automatically.
Building a Smart Converter: Creating an Effective Prompt
The key to making this tool work well is the prompt I designed for Claude API. It’s not just a simple set of instructions—it’s a detailed guide that helps the AI act like an expert who knows both Chef and Ansible inside out. I improved this prompt over time by testing it with real Chef code examples and making adjustments based on the results.
How the Prompt Works
The prompt starts by telling the AI to think like a Chef-to-Ansible migration expert. I used XML tags like <role>, <task>, and <guidelines:variables> to organize different parts of the instructions, which helps the AI understand and follow them better.
Ensuring Quality Ansible Code
A big part of the prompt focuses on Ansible best practices. This includes using Fully Qualified Collection Names (FQCN), writing clear task names, always specifying state parameters, and using proper Boolean values (true/false). I also added rules for handling variables—naming them with snake_case, putting user settings in defaults/main.yml and internal variables in vars/main.yml. The prompt also tells the AI how to handle Chef’s include_attribute statements and find all variables used in templates.
Making the Conversion Reliable
The prompt also covers practical issues like directory handling (creating parent directories before files) and error handling using Ansible features like ignore_errors, failed_when, and block/rescue/always. It includes specific instructions for converting Chef resources, handling notifications (mapping Chef’s :immediately to Ansible’s flush_handlers), and converting Chef’s conditional logic (only_if/not_if) to Ansible’s when conditions. For custom Chef resources that don’t have direct Ansible equivalents, the AI creates clearly-marked placeholder tasks.
Step-by-Step Reasoning
The prompt guides the AI through a clear process: first analyse the Chef recipe, then map resources to Ansible equivalents, organise variables, structure tasks logically, and finally check that everything is complete and correct. I included examples to help the AI learn and built in a feedback system so it can improve from previous attempts. The prompt also requires a specific output format that separates tasks, handlers, and variables, making it easy to organize the final Ansible role.
By giving the AI this detailed guidance, it doesn’t just do a basic translation but really understands what makes good Ansible code. This results in higher quality, more reliable roles that follow Ansible best practices.
Practical Benefits: Making DevOps Work Easier
The tool was designed to assist with Chef to Ansible migrations by automating parts of the conversion process:
The converter helps reduce manual effort by handling the initial translation of Chef cookbooks to Ansible roles. It produces output that follows consistent Ansible best practices and maintains a similar structure across conversions. The approach aims to simplify the migration process, though some manual review and adjustment is still recommended for production use.
How It Works
The converter is built as a Python application with a straightforward yet powerful workflow. It begins by parsing Chef cookbook files to thoroughly understand their structure and relationships. Once the Chef code is properly analyzed, the system sends this parsed code along with the carefully crafted prompt to the Claude API. After receiving the AI-generated Ansible code, the converter performs additional checks and formatting to ensure everything meets quality standards. The final output is a complete, ready-to-use Ansible role that follows best practices. For ease of deployment, the entire solution is packaged in Docker and comes with comprehensive documentation to get teams up and running quickly.
What’s Next
While the current version works well for most common use cases, I’m actively working on several enhancements to make the tool even more powerful. My development roadmap includes expanding support for more complex Chef resources that currently require manual intervention. I’m also designing an interactive mode that will allow users to guide and refine the conversion process as it happens, providing input at critical decision points. For organizations with large Chef infrastructures, I’m developing batch processing capabilities to handle entire cookbook collections simultaneously, significantly speeding up large-scale migrations.
Conclusion
This Chef to Ansible Converter aims to assist with the migration process between these different infrastructure-as-code systems. By combining a structured prompt with AI language models, it helps automate parts of the translation between Chef’s Ruby-based syntax and Ansible’s YAML format. The project demonstrates one practical application of AI to DevOps challenges.
For more information or to contribute to this open-source project, I encourage you to visit the GitHub repository. The repository contains all the source code, including the detailed prompt structure in the src/llm_converter.py file that powers the AI conversion process. Your feedback, bug reports, and pull requests are always welcome as I continue to refine and expand this tool’s capabilities.