mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-06-25 19:55:31 +02:00
112 lines
6.8 KiB
Markdown
112 lines
6.8 KiB
Markdown
## 📖 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](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](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules.html)
|
|
* This conversation: [Link to this conversation](https://chat.openai.com/)
|
|
|
|
---
|
|
|
|
### 🛠️ Repo Layout & Default Directories
|
|
|
|
```plaintext
|
|
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](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](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](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](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](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](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](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](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](https://chatgpt.com/canvas/shared/682b1a62d6dc819184ecdc696c51290a).
|