Creating a Plugin
This guide walks through the full process of creating a plugin from scratch.
Step 1: Create the Plugin
Section titled “Step 1: Create the Plugin”From the Plugin Development homepage, click Add new Plugin. You’ll be prompted for:
- Plugin Name — a descriptive name (e.g., “Install Splunk Forwarder”)
- Plugin Description — what the plugin does (max 600 characters)
- Plugin Type — Action, Role, Application, Vulnerability, Attack, Defense, or File Copy
Your first plugin version is created automatically.
Step 2: The Plugin Editor
Section titled “Step 2: The Plugin Editor”The plugin editor opens with tabs across the top. Each tab controls a different aspect of your plugin:
| Tab | Purpose |
|---|---|
| YAML | Write your Ansible task list |
| Parameters | Define configurable inputs for scenario architects |
| Automated Actions | Auto-update VLAN/Machine settings when your plugin is applied |
| Dependencies | Declare which plugins must run before yours |
| Templates | Set which base VM templates your plugin supports |
| Parent Plugins | Link to server-side plugins your plugin references |
| File Vault | Upload offline resources (installers, scripts, configs) |
| Preview | Test parameter injection and see rendered output |
Step 3: Write Your YAML
Section titled “Step 3: Write Your YAML”Write your Ansible tasks in the YAML tab. You only write the task body — no hosts:, no tasks: header. The system wraps it for you at build time.
See Writing Plugin YAML for the full guide and YAML Examples for real code snippets.
Step 4: Define Parameters
Section titled “Step 4: Define Parameters”Switch to the Parameters tab to create configurable inputs. Parameters are defined in the UI — field name, type, description, required/optional. Then reference them in your YAML with {{ ParamName }}.
See Plugin Parameters for the full guide or CSV Parameters for advanced tabular data.
Step 5: Upload Vault Resources (if needed)
Section titled “Step 5: Upload Vault Resources (if needed)”If your plugin needs files deployed to the VM (Windows installers, scripts, configs), upload them in the File Vault tab. Reference them in your YAML with relative paths.
Linux plugins typically don’t need vault files — apt-get install works out of the box via the APT mirror.
See The File Vault for details.
Step 6: Set Template Compatibility
Section titled “Step 6: Set Template Compatibility”In the Templates tab, toggle which base VM templates your plugin supports. This prevents applying a Windows plugin to a Linux machine and helps users find your plugin with OS filters in the browser.
Step 7: Test Your Plugin
Section titled “Step 7: Test Your Plugin”Create a test scenario, apply your plugin to a machine, set parameter values, and launch a build. Monitor the build logs for Ansible output, fix any issues, and re-deploy.
See Testing Your Plugin for the full workflow.
Step 8: Publish
Section titled “Step 8: Publish”When your plugin works reliably, publish the version to make it available to others (based on your permission settings). Add a changelog entry so users know what the plugin does.