CMDLINE support

README.md

@@ -42,32 +42,53 @@ cd ansible-link
 pip install -r requirements.txt
 ```
 
+* Set config values in `config.yml`
+```yaml
+playbook_dir: '/etc/ansible/'
+inventory_file: '/etc/ansible/environments/hosts'
+```
+
+```shell
+python3 ansible_link/ansible_link.py
+```
+The API will be accessible at localhost:port (default 5001) or wherever you bind it to.
+
 ## API Documentation
 The API documentation is available via Swagger UI.
 
 <img src="docs.png" alt="Ansible Link Docs"  style="margin-right: 20px;">
 
 ## Configuration
-The API configuration is stored in the config.yaml file. You can customize the following settings:
+The API configuration is stored in the `config.yml` file. 
+If you move your config to a different location you can use `ANSIBLE_API_CONFIG` 
+```shell
+$ export ANSIBLE_API_CONFIG='/etc/ansible-link/config.yml'
+```
+
+You can customize the following settings:
 
 ```yaml
+# flask
 host: '127.0.0.1'
 port: 5001
 debug: false
 
-playbook_dir: '/etc/ansible/'
-inventory_dir: '/etc/ansible/hosts'
-ansible_playbook_cmd: 'ansible-playbook'
+# ansible-runner
+suppress_ansible_output: false
+omit_event_data: false
+only_failed_event_data: false
 
+# general
+playbook_dir: '/etc/ansible/'
+inventory_file: '/etc/ansible/environments/hosts'
 job_storage_dir: '/var/lib/ansible-link/job-storage'
-
 log_level: 'INFO'
-log_file: '/var/log/ansible-link/api.log'
-
-playbook_whitelist:
-  - some_allowed_playbook.yml
-  - some_other_allowed_playbook.yml
 
+# ansible-link (leave blank to allow all)
+playbook_whitelist: []
+# playbook_whitelist:
+#   - monitoring.yml
+#   - mariadb.yml
 ```
 
 The whitelist supports <b>full regex</b>, you could go wild:
@@ -82,13 +103,10 @@ playbook_whitelist:
   # Allow specific playbooks
   - ^(backup|restore|maintenance)\.ya?ml$
 ```
-Leave empty to allow all playbooks.
+Leave empty to allow all playbooks. This is for the backend, you could also use the `limit` arg from ansible-runner in the request directly.
+
+## Produciton environment
 
-## Start the API server:
-```shell
-python3 ansible-link.py
-```
-The API will be accessible at localhost:port (default 5001) or wherever you bind it to.
 **Use WSGI for prod ENV (gunicorn) + systemd service**
 
 ### unitd example file
@@ -110,7 +128,6 @@ WantedBy=multi-user.target
 
 ### Example setup:
 ```
-/
 ├── etc/
 │   └── ansible/
 │       ├── playbooks/
@@ -122,18 +139,13 @@ WantedBy=multi-user.target
 ├── opt/
 │   └── ansible-link/
 │       ├── ansible-link.py
-│       ├── config.yml
-│       ├── requirements.txt
-│       └── README.md
+│       └── config.yml
 │
 └── var/
-    ├── lib/
-    │   └── ansible-link/
-    │       └── job-storage/
-    │           └── playbook_name_20230624_130000_job_id.json
-    └── log/
+    └── lib/
         └── ansible-link/
-            └── api.log
+            └── job-storage/
+                └── playbook_name_20230624_130000_job_id.json
 ```
 
 ### API Endpoints
@@ -147,33 +159,125 @@ WantedBy=multi-user.target
 ## Usage
 
 #### Example requests:
-CLI
-```shell
-$ ansible-playbook monitoring_stack.yml
+
+Below are examples demonstrating how to use ansible-link API compared to Ansible CLI.
+
+## Example 1: Basic Playbook Run
+
+```bash
+ansible-playbook site.yml
 ```
 
-API
 ```json
 {
-  "playbook": "monitoring_stack.yml",
+  "playbook": "site.yml"
 }
 ```
+
+```bash
+curl -X POST http://your-ansible-link-server/ansible/playbook \
+  -H "Content-Type: application/json" \
+  -d '{"playbook": "site.yml"}'
+```
 ---
-CLI
-```shell
-$ ansible-playbook monitoring_stack.yml -e customer="mycustomer" --tags="monitoring"
+
+```bash
+ansible-playbook deploy.yml -e version=1.5.0 environment=staging
 ```
 
-API
 ```json
 {
-  "playbook": "monitoring_stack.yml",
+  "playbook": "deploy.yml",
   "vars": {
-    "customer": "mycustomer",
-    "ansible_tags": "monitoring"
+    "version": "1.5.0",
+    "environment": "staging"
   }
 }
 ```
+---
+
+```bash
+ansible-playbook site.yml --tags "update,packages" -vv
+```
+
+```json
+{
+  "playbook": "site.yml",
+  "tags": "update,packages",
+  "verbosity": 2
+}
+```
+---
+
+```bash
+ansible-playbook restore.yml --limit "databases" --forks 3
+```
+
+```json
+{
+  "playbook": "restore.yml",
+  "limit": "databases",
+  "forks": 3
+}
+```
+
+---
+```bash
+ansible-playbook site.yml -i custom_inventory.ini -e '{"key1": "value1", "key2": "value2"}' --tags "provision,configure" --skip-tags "cleanup" --limit "webservers:&staged" --forks 10 -vvv
+```
+
+```json
+{
+  "playbook": "site.yml",
+  "inventory": "custom_inventory.ini",
+  "vars": {
+    "key1": "value1",
+    "key2": "value2"
+  },
+  "tags": "provision,configure",
+  "skip_tags": "cleanup",
+  "limit": "webservers:&staged",
+  "forks": 10,
+  "verbosity": 3
+}
+```
+
+--- 
+
+```bash
+ansible-playbook site.yml -i custom_inventory.ini -e environment=production --diff --check
+```
+
+```json
+{
+  "playbook": "site.yml",
+  "inventory": "custom_inventory.ini",
+  "vars": {
+    "environment": "production"
+  },
+  "cmdline": "--diff --check"
+}
+```
+Ansible-Link supports the following native parameters:
+
+* playbook: The name of the playbook to run (required)
+* inventory: Path to the inventory file
+* vars (extravars): A dictionary of additional variables to pass to the playbook
+* limit: A host pattern to further constrain the list of hosts
+* verbosity: Control the output level of ansible-playbook
+* forks: Specify number of parallel processes to use
+* tags: Only run plays and tasks tagged with these values
+* skip_tags: Only run plays and tasks whose tags do not match these values
+* cmdline: Any additional command line options to pass to ansible-playbook
+
+Which means you can always use cmdline if your arg is not natively supported, like:
+
+```json
+{
+  "playbook": "site.yml",
+  "cmdline": "--diff --check -e environment=production -i /etc/ansible/test/custom_inventory.ini"
+}
+```
 
 ### Output
 Ansible-Link will save each job as .json with the following info (from ansible-runner):
@@ -210,6 +314,8 @@ Ansible-Link will save each job as .json with the following info (from ansible-r
 ```
 essentially showing everything ansible-playbook would display.
 
+<b>Note</b> After submitting a request to the API, you will receive a job ID. You can use this job ID to check the status and retrieve the output of the playbook run using the /ansible/job/<job_id> and /ansible/job/<job_id>/output endpoints respectively.
+
 ## Security Considerations
 * Use TLS in production
 * Add basic auth