Merge pull request #2 from cieslicki/tower_maint

for Tower compatibility, modded readme and NCPA plybook

ansible/ncpa_install_and_register/README.md

@@ -1,26 +1,61 @@
-# Setup
+These playbooks and roles are designed to distribute NCPA -- the Nagios Cross Platform Agent -- to devices in your environment, and then automatically register the devices for basic monitoring with Nagios XI.
 
-You will need to edit two files to get this working:
+Users adapt these files to their environments through required setup and optional setup. Required setup involves information that must be configured for the automation to work. Optional setup involves modifying the Nagios XI API calls used to configure monitoring of the devices to customize how devices are monitored.
 
-1.  Set the IP address of your XI server in `ncpa_install_and_register.yml` like so:
+Once at least the required modifications are made, Tower users can launch the job template, while Ansbile CLI users can run the executable run.sh file.
 
+
+# Required Setup
+
+There are three pieces of information users must supply: 
+1) the IP address or FQDN of the Nagios XI installation
+2) an administrative-level Nagios XI API key
+3) the NCPA authentication token to configure on the devices and XI
+
+
+## Security considerations for required setup
+
+An administrative-level Nagios XI API key can be used to modify XI configs programmatically. Indeed, this automation does exactly that. The NCPA authentication token grants access to NCPA functionality on the monitored device. Users may wish to encrypt the API key and NCPA token with either Tower Custom Credential Types or a vault file.
+
+
+### Fast, less-secure method of required setup
+
+1) Tower: add the items as EXTRA VARIABLES in the Job Template:
+```yml
+---
+xi_ip: '192.168.100.100'
+xi_api_key: 'XFbaUsuPi0OU3n0jmVkCAkYl78t2DodBkI0eav3sP8G8CHrXS5vooNNubAPOX3lh'
+ncpa_token: 'a_secure_token'
+```
+
+2) Ansible CLI: add a vars section above the roles section in ncpa_install_and_register.yml:
 ```yml
   vars:
     xi_ip: '192.168.100.100'
+    xi_api_key: 'XFbaUsuPi0OU3n0jmVkCAkYl78t2DodBkI0eav3sP8G8CHrXS5vooNNubAPOX3lh'
+    ncpa_token: 'a_secure_token'
 ```
 
-2.  Set the XI API Key and the NCPA Token in the encrypted `secrets.yml` file:
+### More-secure method of required setup
+1) Tower: create credential types and credentials for the xi_api_key and ncpa_token vars 
 
-  1.  Run `ansible-vault edit secrets.yml`
-    * It may ask you for the password three times, this is a known ansible bug
-  2.  Enter password `hunter2` as this is the example used
-    * Feel free to change this as you see fit
-  3.  File will look something like this, update to suit your environment:
+2) Ansible CLI: add a vars_files and a vars section above the roles section in ncpa_install_and_register.yml:
+```yml
+  vars_files:
+    - 'secrets.yml'
+  vars:
+    xi_ip: '192.168.100.100'
+```
 
+Set the XI API Key and the NCPA Token in the vault-encrypted secrets.yml file:
+Run ansible-vault edit secrets.yml * It may ask you for the password three times, this is a known ansible bug
+Enter password hunter2 as this is the example used * Feel free to change this as you see fit
+File will look something like this, update to suit your environment:
 ```yml
 ---
 xi_api_key: 'XFbaUsuPi0OU3n0jmVkCAkYl78t2DodBkI0eav3sP8G8CHrXS5vooNNubAPOX3lh'
 ncpa_token: 'DabohKGprhau'
 ```
 
-Finally, just run `run.sh` and it should be good to go.
+# Optional Setup
+This automation auto-registers the inventory as hosts in XI, and also configures predefined service monitoring. Users may like to know that they can add additional custom API calls to the automation, or remove those provided API calls they wish not to use. As a full discussion of the Nagios XI API is out of scope for this document, users are directed to the Help page in the Nagios XI interface, which has API documentation and examples of API calls.

ansible/ncpa_install_and_register/ncpa_install_and_register.yml

@@ -3,11 +3,6 @@
   hosts: all
   remote_user: root
 
-  vars_files:
-    - 'secrets.yml'
-  vars:
-    xi_ip: '192.168.100.100'
-
   roles:
     - role: ncpa_install_linux
     - role: register_with_xi