From 2aeb31d1d3f5b08bf5c7d0ee634357056c1dd230 Mon Sep 17 00:00:00 2001 From: imilev Date: Sat, 5 Jul 2025 02:09:08 +0300 Subject: [PATCH] Added high-level diagrams --- .codeboarding/Ansible_Base_Runner.md | 79 +++++++++ .codeboarding/Specific_Ansible_Actions.md | 195 ++++++++++++++++++++++ .codeboarding/on_boarding.md | 167 ++++++++++++++++++ 3 files changed, 441 insertions(+) create mode 100644 .codeboarding/Ansible_Base_Runner.md create mode 100644 .codeboarding/Specific_Ansible_Actions.md create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/Ansible_Base_Runner.md b/.codeboarding/Ansible_Base_Runner.md new file mode 100644 index 0000000..f0c7609 --- /dev/null +++ b/.codeboarding/Ansible_Base_Runner.md @@ -0,0 +1,79 @@ +```mermaid + +graph LR + + AnsibleBaseRunner["AnsibleBaseRunner"] + + Shell_Utility["Shell Utility"] + + AnsibleBaseRunner -- "relies on" --> Shell_Utility + +``` + + + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Details + + + +The Ansible Base Runner subsystem is a foundational Python library designed to encapsulate the common logic required for executing various Ansible commands within a StackStorm environment. It promotes code reusability and consistency across different Ansible-related actions. + + + +### AnsibleBaseRunner + +This is the core abstract base class of the Ansible Base Runner subsystem. It provides the foundational logic for executing various Ansible commands. Its responsibilities include: Input Parameter Parsing: Specifically handles the transformation of --extra_vars arguments (_parse_extra_vars). Environment Management: Ensures correct Ansible execution by prepending the virtual environment path to the system's PATH (_prepend_venv_path). Command Construction: Dynamically builds the full command-line arguments for Ansible binaries (via the cmd property). Binary Resolution: Locates the correct Ansible binary within the environment (via the binary property). External Command Invocation: Executes the constructed command using subprocess.call and handles exit codes (via the execute method). It acts as an Adapter and Facade for Ansible's command-line interface, abstracting the underlying shell execution details for all specific Ansible actions that inherit from it. + + + + + +**Related Classes/Methods**: + + + +- `ansible_base.AnsibleBaseRunner` (14:141) + +- `ansible_base.AnsibleBaseRunner:_parse_extra_vars` (30:85) + +- `ansible_base.AnsibleBaseRunner:_prepend_venv_path` (88:97) + +- `ansible_base.AnsibleBaseRunner:cmd` (112:119) + +- `ansible_base.AnsibleBaseRunner:binary` (122:141) + +- `ansible_base.AnsibleBaseRunner:execute` (99:108) + + + + + +### Shell Utility + +This component provides utility functions specifically designed for processing and manipulating shell command arguments. Its primary role is to assist the AnsibleBaseRunner by applying specific replacement rules to command arguments before they are executed, ensuring proper formatting and handling of shell-specific nuances. + + + + + +**Related Classes/Methods**: + + + +- `shell` (1:1) + +- `shell:replace_args` (7:29) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Specific_Ansible_Actions.md b/.codeboarding/Specific_Ansible_Actions.md new file mode 100644 index 0000000..3b34ffc --- /dev/null +++ b/.codeboarding/Specific_Ansible_Actions.md @@ -0,0 +1,195 @@ +```mermaid + +graph LR + + AnsibleBaseRunner["AnsibleBaseRunner"] + + AnsiblePlaybookAction["AnsiblePlaybookAction"] + + AnsibleCommandAction["AnsibleCommandAction"] + + AnsibleGalaxyAction["AnsibleGalaxyAction"] + + AnsibleVaultAction["AnsibleVaultAction"] + + Shell_Utility_Module["Shell Utility Module"] + + YAML_Action_Definitions_Specific_Actions_["YAML Action Definitions (Specific Actions)"] + + AnsiblePlaybookAction -- "inherits from" --> AnsibleBaseRunner + + AnsibleCommandAction -- "inherits from" --> AnsibleBaseRunner + + AnsibleGalaxyAction -- "inherits from" --> AnsibleBaseRunner + + AnsibleVaultAction -- "inherits from" --> AnsibleBaseRunner + + AnsibleBaseRunner -- "uses" --> Shell_Utility_Module + + YAML_Action_Definitions_Specific_Actions_ -- "defines interface for" --> AnsiblePlaybookAction + + YAML_Action_Definitions_Specific_Actions_ -- "defines interface for" --> AnsibleCommandAction + + YAML_Action_Definitions_Specific_Actions_ -- "defines interface for" --> AnsibleGalaxyAction + + YAML_Action_Definitions_Specific_Actions_ -- "defines interface for" --> AnsibleVaultAction + +``` + + + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Details + + + +The "Specific Ansible Actions" component is a critical part of the StackStorm Ansible Integration Pack, serving as the direct interface between StackStorm's orchestration capabilities and Ansible's configuration management tools. This subsystem is designed with a clear separation of concerns, leveraging inheritance and the Adapter pattern to provide a robust and extensible set of actions. The core of this subsystem revolves around a base runner that handles common Ansible execution logic, which is then extended by individual action classes tailored for specific Ansible binaries. + + + +### AnsibleBaseRunner + +This is the foundational abstract component providing the common execution framework for all Ansible-related StackStorm Python actions. It encapsulates logic for setting up the execution environment (e.g., prepending virtual environment paths), parsing and transforming complex `extra_vars` arguments, dynamically constructing the Ansible command line, and executing the command via a subprocess. It acts as an Adapter for the underlying shell execution of Ansible commands. + + + + + +**Related Classes/Methods**: + + + +- `AnsibleBaseRunner` (1:1) + + + + + +### AnsiblePlaybookAction + +This component is a concrete StackStorm Python action specifically designed to execute Ansible playbooks. It extends `AnsibleBaseRunner`, inheriting its core execution logic, and primarily defines the `ansible-playbook` binary name and any specific argument replacement rules unique to playbook execution. + + + + + +**Related Classes/Methods**: + + + +- `AnsiblePlaybookAction` (1:1) + + + + + +### AnsibleCommandAction + +This component is a concrete StackStorm Python action responsible for executing arbitrary Ansible ad-hoc commands. Like `AnsiblePlaybookAction`, it extends `AnsibleBaseRunner` and specifies the `ansible` binary name along with any ad-hoc command-specific argument handling. + + + + + +**Related Classes/Methods**: + + + +- `AnsibleCommandAction` (1:1) + + + + + +### AnsibleGalaxyAction + +This component is a concrete StackStorm Python action dedicated to managing Ansible Galaxy operations (e.g., installing or removing roles and collections). It extends `AnsibleBaseRunner` and configures the `ansible-galaxy` binary and its unique argument replacement rules. + + + + + +**Related Classes/Methods**: + + + +- `AnsibleGalaxyAction` (1:1) + + + + + +### AnsibleVaultAction + +This component is a concrete StackStorm Python action for handling Ansible Vault operations, such as encrypting or decrypting sensitive files. It extends `AnsibleBaseRunner` and defines the `ansible-vault` binary and its specific argument handling. + + + + + +**Related Classes/Methods**: + + + +- `AnsibleVaultAction` (1:1) + + + + + +### Shell Utility Module + +This is a utility module that provides helper functions, particularly a decorator (`replace_args`), used by `AnsibleBaseRunner` to dynamically modify command-line arguments before execution. It abstracts common shell-related operations. + + + + + +**Related Classes/Methods**: + + + +- `shell` (1:1) + + + + + +### YAML Action Definitions (Specific Actions) + +These YAML files serve as the public interface for the Python actions within StackStorm. Each file defines a specific action's metadata, including its name, description, and crucially, its input parameters (with types, defaults, and descriptions). They map the StackStorm action invocation to the underlying Python script. + + + + + +**Related Classes/Methods**: + + + +- `playbook.yaml` (1:1) + +- `command.yaml` (1:1) + +- `galaxy.install.yaml` (1:1) + +- `galaxy.list.yaml` (1:1) + +- `galaxy.remove.yaml` (1:1) + +- `vault.decrypt.yaml` (1:1) + +- `vault.encrypt.yaml` (1:1) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 0000000..f6dab57 --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,167 @@ +```mermaid + +graph LR + + StackStorm_Pack_Definition["StackStorm Pack Definition"] + + Ansible_Base_Runner["Ansible Base Runner"] + + Specific_Ansible_Actions["Specific Ansible Actions"] + + Python_Dependency_Manager["Python Dependency Manager"] + + Testing_Framework["Testing Framework"] + + StackStorm_Pack_Definition -- "Registers" --> Specific_Ansible_Actions + + StackStorm_Pack_Definition -- "Provides Configuration To" --> Specific_Ansible_Actions + + Ansible_Base_Runner -- "Is Inherited By" --> Specific_Ansible_Actions + + Ansible_Base_Runner -- "Relies On" --> Python_Dependency_Manager + + Specific_Ansible_Actions -- "Extends/Utilizes" --> Ansible_Base_Runner + + Specific_Ansible_Actions -- "Registered By" --> StackStorm_Pack_Definition + + Python_Dependency_Manager -- "Provides Dependencies For" --> Ansible_Base_Runner + + Python_Dependency_Manager -- "Provides Dependencies For" --> Specific_Ansible_Actions + + Testing_Framework -- "Validates" --> Ansible_Base_Runner + + Testing_Framework -- "Validates" --> Specific_Ansible_Actions + + click Ansible_Base_Runner href "https://github.com/recursionpharma/stackstorm_pack_ansible/blob/trunk/.codeboarding//Ansible_Base_Runner.md" "Details" + + click Specific_Ansible_Actions href "https://github.com/recursionpharma/stackstorm_pack_ansible/blob/trunk/.codeboarding//Specific_Ansible_Actions.md" "Details" + +``` + + + +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + + + +## Details + + + +This StackStorm Integration Pack is designed to expose Ansible's capabilities as discrete, executable actions within the StackStorm automation platform. Its architecture emphasizes modularity, reusability, and clear separation of concerns, leveraging Python for core logic and YAML for StackStorm-specific definitions. + + + +### StackStorm Pack Definition + +This component serves as the primary configuration and registration point for the entire pack within StackStorm. It defines the pack's metadata and explicitly registers all available Ansible actions (e.g., playbook execution, Galaxy management, Vault operations, generic commands) through their respective YAML definitions. It orchestrates how StackStorm discovers and loads the pack's functionalities. + + + + + +**Related Classes/Methods**: + + + +- `pack.yaml` (1:1) + +- `actions/playbook.yaml` (1:1) + +- `actions/galaxy.install.yaml` (1:1) + +- `actions/vault.decrypt.yaml` (1:1) + +- `actions/command.yaml` (1:1) + + + + + +### Ansible Base Runner [[Expand]](./Ansible_Base_Runner.md) + +This is the foundational Python library that encapsulates the common logic for executing various Ansible commands. It handles critical tasks such as parsing input parameters, managing virtual environments to ensure correct Ansible execution, constructing command-line arguments, and invoking external shell commands via `subprocess.call`. It acts as the abstract base class from which all specific Ansible actions inherit their core execution capabilities. + + + + + +**Related Classes/Methods**: + + + +- `actions/lib/ansible_base.py` (1:1) + +- `actions/lib/shell.py` (1:1) + + + + + +### Specific Ansible Actions [[Expand]](./Specific_Ansible_Actions.md) + +This component represents the collection of individual StackStorm Python actions, each tailored to perform a distinct Ansible operation. These actions (e.g., `ansible_playbook.py`, `ansible_galaxy.py`, `ansible_vault.py`, `ansible.py`) extend the `Ansible Base Runner`, inheriting its core execution logic while defining specific argument handling and command-line construction rules for their respective Ansible tools. They are the direct interface between StackStorm and Ansible. + + + + + +**Related Classes/Methods**: + + + +- `actions/ansible_playbook.py` (1:1) + +- `actions/ansible_galaxy.py` (1:1) + +- `actions/ansible_vault.py` (1:1) + +- `actions/ansible.py` (1:1) + + + + + +### Python Dependency Manager + +This component is responsible for specifying and managing all external Python libraries required for the pack's proper functioning. It ensures that the necessary dependencies (e.g., `pywinrm`, `netaddr`, `boto3`) are available and correctly installed within StackStorm's virtual environment, providing a consistent and reproducible execution context for all Python-based components. + + + + + +**Related Classes/Methods**: + + + +- `requirements.txt` (1:1) + + + + + +### Testing Framework + +This component comprises the unit and integration tests designed to validate the correctness and reliability of the pack's actions and shared libraries. It ensures that the `Ansible Base Runner` correctly constructs and executes Ansible commands, and that the `Specific Ansible Actions` behave as expected, providing confidence in the pack's overall functionality. + + + + + +**Related Classes/Methods**: + + + +- `tests/test_actions_lib_ansiblebaserunner.py` (1:1) + +- `tests/fixtures/example.txt` (1:1) + + + + + + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file