From 05b95e20a412ad5d35d07a60af338f8deab0bc3a Mon Sep 17 00:00:00 2001 From: Tyler Levy Conde Date: Wed, 28 Aug 2024 11:12:45 -0600 Subject: [PATCH] Convert to README.md --- README.md | 210 +++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 125 ----------------------------- pyproject.toml | 2 +- 3 files changed, 211 insertions(+), 126 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..a69a33b --- /dev/null +++ b/README.md @@ -0,0 +1,210 @@ +# Soluble + +![Made with POP](https://img.shields.io/badge/made%20with-pop-teal) +![Made with Python](https://img.shields.io/badge/made%20with-python-yellow) + +**Soluble** is a versatile tool for setting up, managing, and tearing down ephemeral agents on remote systems using `salt-ssh`. While the primary use case is for creating ephemeral Salt minions, Soluble can also be used to spin up ephemeral Salt masters or any other kind of agent through custom plugins. This makes it an ideal tool for transient infrastructure needs. + +## About + +Soluble aims to streamline the deployment of ephemeral nodes, allowing users to execute Salt commands on these nodes before safely removing them. The process is managed by a Python script that leverages `salt-ssh` to target machines in a roster, performing setup, execution, and teardown of agents. Soluble is highly extensible, allowing for the creation of custom plugins to manage different types of ephemeral agents. + +### What is POP? + +This project is built with [POP](https://pop.readthedocs.io/), a Python-based implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring together concepts and wisdom from the history of computing in new ways to solve modern computing problems. + +For more information: + +- [Intro to Plugin Oriented Programming (POP)](https://pop-book.readthedocs.io/en/latest/) +- [pop-awesome](https://gitlab.com/vmware/pop/pop-awesome) +- [pop-create](https://gitlab.com/vmware/pop/pop-create/) + +## Getting Started + +### Prerequisites + +- Python 3.10+ +- Git (if installing from source or contributing to the project) +- SaltStack installed on the master node +- `salt` and `salt-key` commands available + +### Installation + +You can install `soluble` either from [PyPI](https://pypi.org/project/soluble/) or from source on [GitHub](https://github.com/saltstack/soluble). + +#### Install from PyPI + +```bash +pip install soluble +``` + +#### Install from Source + +```bash +# Clone the repository +git clone https://github.com/saltstack/soluble.git +cd soluble + +# Setup a virtual environment +python3 -m venv .venv +source .venv/bin/activate +pip install -e . +``` + +## Usage + +Soluble uses `salt-ssh` to set up ephemeral agents, perform actions on these agents, and then tear them down. + +### Plugins + +A soluble plugin contains a `conf.py` and a `soluble` directory containing the Python file for the plugin. Each plugin must contain three functions: `setup`, `run`, and `teardown`. + +- **`setup`:** Prepares the soluble agent. For example, installing and starting `salt-minion` or setting up a Salt master. +- **`run`:** Executes the primary function of the plugin. This is the only function that should print to stdout. +- **`teardown`:** Undoes everything that was done in `setup` and removes any artifacts left behind by `run` as necessary. + +The master and minion plugins in this project are structured as examples for creating external plugins. + +### Python Code Examples + +Below is an example of how to implement the `setup`, `run`, and `teardown` functions in a soluble plugin. +This example comes from the `init` plugin, which is a basic plugin that uses `salt-ssh` to perform a simple ping operation. + +```python +# project_root//soluble/.py + + +async def setup(hub, name: str): + """This is where a soluble plugin uses salt-ssh to prepare the roster targets""" + hub.log.info("Soluble setup") + # Set a custom config value in the RUN dictionary that will be needed for `run` and `teardown` + hub.soluble.RUN[name].my_key = "my value" + await hub.salt.ssh.run_command( + name, + f"test.ping", + ) + + +async def run(hub, name: str) -> int: + """This is where a soluble plugin runs its primary function""" + hub.log.info("Soluble run") + await hub.salt.ssh.run_command(name, f"test.ping", capture_output=False) + return 0 + + +async def teardown(hub, name: str): + """This is where a soluble function undoes everything from the setup process""" + hub.log.info("Soluble teardown") + await hub.salt.ssh.run_command( + name, + f"test.ping", + ) +``` + +### CLI and Configuration + +The `name` argument is passed to all the functions. `setup` can add keyword arguments as needed for `run` and `teardown` to the `RUN` dictionary, which is accessed with: + +```python +hub.soluble.RUN[name] +``` + +Also, CLI arguments exist in a mutable format within that `RUN` dictionary. + +You can add options to the CLI specific to your command by including them in your plugin's `conf.py`: + +```python +# project_root//conf.py + +# Defining options in the CONFIG dictionary means `soluble` will look for them in a config file +CONFIG = { + "my_custom_opt": { + "default": "default value", + "help": "", + # This ensures that your option is added to hub.soluble.RUN[name] + "dyne": "soluble", + }, +} + +# Defining options in the CLI_CONFIG dictionary means they will be available on the CLI +CLI_CONFIG = { + "my_custom_opt": {"subcommands": [""]}, +} + +DYNE = {"soluble": ["soluble"]} +``` + +### Examples + +Soluble simplifies the process of setting up ephemeral agents, running commands, and then cleaning up those agents. +Plain `salt-ssh` gives you a small subset of the full capability of salt. `soluble minion` gives you the +ephemeral nature of `salt-ssh` commands, but with the *full* power of salt. + +Here’s a basic usage example: + +```bash +soluble -R /path/to/roster minion '*' test.ping +``` + +In this example: +- The `-R` flag specifies the path to the roster file for `salt-ssh`. +- The first positional argument (`test.ping`) is the Salt command to be executed on the ephemeral minions. + +#### Basic Soluble Plugins + +There are three basic soluble plugins: `init`, `minion`, and `master`. + +- **Init Plugin Example:** + + The init plugin just does a "test.ping" with `salt-ssh`. + + ```bash + soluble -R /path/to/roster init '*' + ``` + +- **Soluble Minion Examples:** + + ```bash + # Install a package on ephemeral nodes + soluble minion '*' pkg.install vim + + # Apply a state file + soluble minion '*' state.apply my_state + + # Ping minions + soluble minion '*' test.ping + ``` + +- **Soluble Master Example:** + + This will spin up a master on the roster targets until you hit CTRL-C. + + ```bash + soluble -R /path/to/roster master --master-config=/path/to/config '*' + ``` + + To leave the master running indefinitely, add the `--bootstrap` flag. + + ```bash + soluble -R /path/to/roster master --master-config=/path/to/config '*' --bootstrap + ``` + +## Roadmap + +Refer to the [open issues](https://github.com/saltstack/soluble/issues) for a list of proposed features and known issues. + +The project roadmap includes: +- Expanding support for additional Salt modules and functions. +- Enhancing error handling and logging for more robust operation. +- Integration with other infrastructure management tools. + +## Acknowledgements + +- [Img Shields](https://shields.io) for making repository badges easy. + +--- + +### Key Additions and Enhancements: +- **Expanded Scope:** The README now reflects the broader capabilities of Soluble, including support for ephemeral Salt masters and other agents. +- **Python Code Examples:** Added detailed examples of how to implement `setup`, `run`, and `teardown` in a soluble plugin. +- **Plugin Customization:** Clarified how CLI options can be customized for specific plugins via `conf.py`. diff --git a/README.rst b/README.rst deleted file mode 100644 index d233227..0000000 --- a/README.rst +++ /dev/null @@ -1,125 +0,0 @@ -======= -soluble -======= - -.. image:: https://img.shields.io/badge/made%20with-pop-teal - :alt: Made with pop, a Python implementation of Plugin Oriented Programming - :target: https://pop.readthedocs.io/ - -.. image:: https://img.shields.io/badge/made%20with-python-yellow - :alt: Made with Python - :target: https://www.python.org/ - -Soluble is a tool for setting up, managing, and tearing down ephemeral Salt minions on remote systems u -sing a streamlined Python-based approach. It simplifies the deployment of temporary nodes that can -execute Salt commands and clean up afterward, making it ideal for transient infrastructure needs. - -About -===== - -Soluble is designed aims to streamline the deployment of ephemeral nodes with Salt leveraging `salt-ssh` -for setting up and tearing down temporary Salt minions, allowing users to execute Salt commands on these -minions before safely removing them. The entire process is managed by a Python script, ensuring ease of use, -flexibility, and integration with existing Python-based infrastructure. - -What is POP? ------------- - -This project is built with `pop `__, a Python-based implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring together concepts and wisdom from the history of computing in new ways to solve modern computing problems. - -For more information: - -* `Intro to Plugin Oriented Programming (POP) `__ -* `pop-awesome `__ -* `pop-create `__ - -Getting Started -=============== - -Prerequisites -------------- - -* Python 3.10+ -* git *(if installing from source, or contributing to the project)* -* SaltStack installed on the master node -* `salt` and `salt-key` commands available - -Installation ------------- - -.. note:: - - If wanting to contribute to the project, and setup your local development - environment, see the ``CONTRIBUTING.rst`` document in the source repository - for this project. - -If wanting to use ``soluble``, you can do so by either installing from PyPI or from source. - -Install from PyPI -+++++++++++++++++ - -If package is available via PyPI, include the directions. - -.. code-block:: bash - - pip install soluble - -Install from source -+++++++++++++++++++ - -.. code-block:: bash - - # clone repo - git clone git@/soluble.git - cd soluble - - # Setup venv - python3 -m venv .venv - source .venv/bin/activate - pip install -e . - -Usage -===== - -Soluble is designed to simplify the process of setting up ephemeral Salt minions, running commands, -and then cleaning up those minions. Here’s a basic usage example: - -.. code-block:: bash - - # Example usage of soluble.py - soluble -R /path/to/roster 'test.ping' - -In this example: -- The `-R` flag specifies the path to the roster file for `salt-ssh`. -- The first positional argument (`test.ping`) is the Salt command to be executed on the ephemeral minions. - -Examples --------- - -Here are a few more examples of how you can use Soluble: - -.. code-block:: bash - - # Install a package on ephemeral nodes - soluble minion '*' 'pkg.install vim' - - # Apply a state file - soluble '*' 'state.apply my_state' - - # Ping minions - soluble minion '*' 'test.ping' - -Roadmap -======= - -Reference the `open issues `__ for a list of proposed features (and known issues). - -The project roadmap includes: -- Expanding support for additional Salt modules and functions. -- Enhancing error handling and logging for more robust operation. -- Integration with other infrastructure management tools. - -Acknowledgements -================ - -* `Img Shields `__ for making repository badges easy. diff --git a/pyproject.toml b/pyproject.toml index 1d17693..2b1ae10 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" name = "soluble" version = "3.0.0" description = "Set up a dissolvable, ephemeral salt minion using salt-ssh" -readme = "README.rst" +readme = "README.md" url = "https://github.com/saltstack/soluble" authors = [ {name = "Tyler Levy Conde", email = "tyler.levy-conde@broadcomm.com"},