computer-playbook/docs/guides/developer/Ansible_Directory_Guide.md

📖 CyMaIS.Cloud Ansible & Python Directory Guide

This document provides a decision matrix for when to use each default Ansible plugin and module directory in the context of CyMaIS.Cloud development with Ansible and Python. It links to official docs, explains use-cases, and points back to our conversation.

---

🔗 Links & References

• Official Ansible Plugin Guide: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html
• Official Ansible Module Guide: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules.html
• This conversation: Link to this conversation

---

🛠️ Repo Layout & Default Directories

ansible-repo/
├── library/                # 📦 Custom Ansible modules
├── filter_plugins/         # 🔍 Custom Jinja2 filters
├── lookup_plugins/         # 👉 Custom lookup plugins
├── module_utils/           # 🛠️ Shared Python helpers for modules
├── action_plugins/         # ⚙️ Task-level orchestration logic
├── callback_plugins/       # 📣 Event callbacks (logging, notifications)
├── inventory_plugins/      # 🌐 Dynamic inventory sources
├── strategy_plugins/       # 🧠 Task execution strategies
└── ...                     # Other plugin dirs (connection, cache, etc.)

---

🎯 Decision Matrix: Which Folder for What?

Folder	Type	Use-Case	Example (CyMaIS.Cloud)	Emoji
library/	Module	Write idempotent actions	cloud_network.py: manage VPCs, subnets	📦
filter_plugins/	Filter plugin	Jinja2 data transforms in templates/vars	to_camel_case.py: convert keys for API calls	🔍
lookup_plugins/	Lookup plugin	Fetch external/secure data at runtime	vault_lookup.py: pull secrets from CyMaIS Vault	👉
module_utils/	Utility library	Shared Python code for modules	cymais_client.py: common API client base class	🛠️
action_plugins/	Action plugin	Complex task orchestration wrappers	deploy_stack.py: sequence Terraform + Ansible steps	⚙️
callback_plugins/	Callback plugin	Customize log/report behavior	notify_slack.py: send playbook status to Slack	📣
inventory_plugins/	Inventory plugin	Dynamic host/group sources	azure_inventory.py: list hosts from Azure tags	🌐
strategy_plugins/	Strategy plugin	Control task execution order/parallelism	rolling_batch.py: phased rollout of VMs	🧠

---

📝 Detailed Guidance

1. library/ 📦

   • When? Implement one-off, idempotent actions (create/delete cloud resources).
   • Why? Modules under library/ are first in search path for ansible modules.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules.html

2. filter_plugins/ 🔍

   • When? You need data manipulation (lists, strings, dicts) inside Jinja2.
   • Why? Extends | filters in templates and variable declarations.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#filter-plugins

3. lookup_plugins/ 👉

   • When? You must retrieve secret/external data during playbook compile/runtime.
   • Why? Lookup plugins run before tasks, enabling dynamic variable resolution.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#lookup-plugins

4. module_utils/ 🛠️

   • When? Multiple modules share common Python code (HTTP clients, validation).
   • Why? Avoid code duplication; modules import these utilities.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules.html#module-utils

5. action_plugins/ ⚙️

   • When? You need to wrap or extend module behavior at task invocation time.
   • Why? Provides hooks before/after module execution.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#action-plugins

6. callback_plugins/ 📣

   • When? You want custom event handlers (logging, progress, notifications).
   • Why? Receive play/task events for custom output.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#callback-plugins

7. inventory_plugins/ 🌐

   • When? Hosts/groups come from dynamic sources (cloud APIs, databases).
   • Why? Replace static inventory.ini with code-driven inventories.
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#inventory-plugins

8. strategy_plugins/ 🧠

   • When? You need to customize execution strategy (parallelism, ordering).
   • Why? Override default linear strategy (e.g., free, custom batches).
   • Docs: https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#strategy-plugins

---

🚀 CyMaIS.Cloud Best Practices

• Organize modules by service under library/cloud/ (e.g., vm, network, storage).
• Shared client code in module_utils/cymais/ for authentication, request handling.
• Secrets lookup via lookup_plugins/vault_lookup.py pointing to CyMaIS Vault.
• Filters to normalize data formats from cloud APIs (e.g., snake_to_camel).
• Callbacks to stream playbook results into CyMaIS Monitoring.

Use this matrix as your single source of truth when extending Ansible for CyMaIS.Cloud! 👍

---

This matrix was created with the help of ChatGPT 🤖—see our conversation here.