From 3cf0ca0905888b2e66fceb3b7a46e04dea9f3858 Mon Sep 17 00:00:00 2001 From: Gavin Didrichsen Date: Tue, 28 Oct 2025 19:18:15 +0000 Subject: [PATCH] Update the documentation Signed-off-by: Gavin Didrichsen --- README.md | 17 ++++++--- docs/how_to/how_to_setup_the_environment.md | 26 +++++++++++++- ...how_to_test_vmpooler_inventory_features.md | 35 +++++++++++++++++++ .../how_to_use_as_a_bolt_dynamic_plugin.md | 2 ++ docs/how_to/how_to_use_as_a_gem.md | 10 ++++-- 5 files changed, 83 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a9bfe2e..937fe0f 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,22 @@ A Bolt inventory generator for VMs on various providers including orbstack and vmpooler. +## Prerequisites + +### System Dependencies + +- **Ruby** (version 2.7 or later) +- **nmap** (required for VMPooler connectivity filtering). For example, `brew install nmap` +- **floaty** (required for VMPooler). For example, `gem install floaty`. +- **bolt** + ## Usage This `bolt_dynamic_inventory` gem queries either VMPooler or Orbstack and generates a Bolt inventory. It can be used in 2 ways: -* **as a gem**. For more information see [How to use as a gem](./docs/how_to/how_to_use_as_a_gem.md). -* **as a bolt dynamic inventory plugin**. For more information see [How to use as a bolt dynamic plugin](./docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md). +- **as a gem**. For more information see [How to use as a gem](./docs/how_to/how_to_use_as_a_gem.md). +- **as a bolt dynamic inventory plugin**. For more information see [How to use as a bolt dynamic plugin](./docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md). -This repository also explains [How to create a basic dynamic inventory plugin](./docs/how_to/how_to_create_a_basic_bolt_inventory_plugin.md). +This repository also explains [How to create a basic dynamic inventory plugin](./docs/how_to/how_to_create_a_basic_bolt_inventory_plugin.md). -For a listing of various how-to guides and design decisions, see [here](./docs/README.md). +For a listing of various how-to guides and design decisions, see the [documentation](./docs/README.md). diff --git a/docs/how_to/how_to_setup_the_environment.md b/docs/how_to/how_to_setup_the_environment.md index 7e566bb..e1c20ab 100644 --- a/docs/how_to/how_to_setup_the_environment.md +++ b/docs/how_to/how_to_setup_the_environment.md @@ -20,7 +20,29 @@ For more information on how to do the above from the command-line see [Create an ### VMPooler Provider -Install and configure `floaty`: +#### Install nmap (Required for VM connectivity filtering) + +**macOS:** + +```bash +brew install nmap +``` + +**Ubuntu/Debian:** + +```bash +sudo apt-get install nmap +``` + +**RHEL/CentOS:** + +```bash +sudo yum install nmap +# or on newer versions: +sudo dnf install nmap +``` + +#### Install and configure floaty ```bash gem install floaty @@ -34,6 +56,8 @@ token: your_token EOL ``` +#### Configure Windows credentials + Configure Windows credentials for VMPooler by setting the appropriate environment variable: ```bash diff --git a/docs/how_to/how_to_test_vmpooler_inventory_features.md b/docs/how_to/how_to_test_vmpooler_inventory_features.md index 1aca541..927786c 100644 --- a/docs/how_to/how_to_test_vmpooler_inventory_features.md +++ b/docs/how_to/how_to_test_vmpooler_inventory_features.md @@ -7,6 +7,7 @@ This guide shows you how to manually test the VMPooler inventory features to ens * Access to VMPooler * Bolt installed * The bolt_dynamic_inventory module installed +* `nmap` installed (required for VM connectivity filtering) ## Test Scenarios @@ -60,6 +61,35 @@ Verify: * 'agent' group exists and contains VMs matching the pattern * Group facts and configurations are correct +### 4. VM Connectivity Filtering Testing + +```bash +# 1. Create test VMs: +bundle exec floaty get ubuntu-2004-x86_64 +bundle exec floaty get ubuntu-2004-x86_64 + +# 2. Note the VM names from the output +# e.g., "tender-punditry.delivery.puppetlabs.net" and "normal-meddling.delivery.puppetlabs.net" + +# 3. Generate inventory (all VMs should be included initially) +binv generate --provider vmpooler + +# 4. Destroy one of the VMs through VMPooler web interface or floaty +bundle exec floaty delete + +# 5. Generate inventory again - destroyed VM should be automatically filtered out +binv generate --provider vmpooler +``` + +Verify: + +* Only reachable VMs appear in the inventory +* Destroyed VMs are automatically excluded from the targets +* The filtering happens automatically without manual intervention +* nmap connectivity checks work correctly for both Linux and Windows VMs + +**Note:** The connectivity filtering uses `nmap -Pn -p 22` to check SSH port availability, which works for both Linux and Windows VMPooler VMs. + ## Cleanup After testing, remember to delete your test VMs: @@ -73,3 +103,8 @@ bundle exec floaty delete * If inventory generation fails, check VMPooler connectivity * Verify VM hostnames in floaty output match expected patterns * Check Windows credentials are properly configured if testing Windows VMs +* **nmap not found error**: Ensure `nmap` is installed on your system (see environment setup guide) +* **Connectivity filtering issues**: + * Verify nmap can reach VMPooler network (test with `nmap -Pn -p 22 `) + * Check firewall rules if VMs appear unreachable but should be accessible + * DNS resolution issues may cause VMs to be filtered out diff --git a/docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md b/docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md index 129fa3b..8fcef38 100644 --- a/docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md +++ b/docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md @@ -10,6 +10,8 @@ For more information see [How to create a basic dynamic inventory plugin](./how_ First, refer to the [Environment Setup Guide](how_to_setup_environment.md) and then configure [orbstack](https://docs.orbstack.dev) and [VMPooler](https://vmpooler.com/). +**Important for VMPooler users:** Ensure `nmap` is installed on your system for VM connectivity filtering (see Environment Setup Guide for installation instructions). + If you are going to be using the vmpooler provider, you will need to also follow [How to setup windows credentials for vmpooler](how_to_setup_windows_credentials_for_vmpooler.md) ## Usage diff --git a/docs/how_to/how_to_use_as_a_gem.md b/docs/how_to/how_to_use_as_a_gem.md index bb18659..e063e8e 100644 --- a/docs/how_to/how_to_use_as_a_gem.md +++ b/docs/how_to/how_to_use_as_a_gem.md @@ -4,7 +4,13 @@ The following shows how to use the [bolt_dynamic_inventory](https://github.com/gavindidrichsen/bolt_dynamic_inventory) as a gem to generate a bolt inventory for multiple providers, including `orbstack` and `vmpooler`. -Then generate an inventory according to the following sections. +## Prerequisites + +For VMPooler provider, ensure `nmap` is installed on your system for VM connectivity filtering: + +**macOS:** `brew install nmap` +**Ubuntu/Debian:** `sudo apt-get install nmap` +**RHEL/CentOS:** `sudo yum install nmap` or `sudo dnf install nmap` ## Usage @@ -26,7 +32,7 @@ rbenv which binv binv # list all VMs binv --groups "agent:^agent,compiler:^compiler" # add custom regex groups -# List vmpooler VMs +# List vmpooler VMs (automatically filters out destroyed/unreachable VMs) binv --provider=vmpooler # list all VMs grouping windows and linux binv --provider=vmpooler --groups "agent:tender|normal" # add custom regex groups