Merge pull request #3 from UKCloud/documentation-for-lookups

andrew-garner · web-flow · commit 1dbfa73e5cd0 · 2021-03-15T15:28:42.000Z
Documentation update for the uptime_checks lookup
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@
 # Ansible
 **/*.retry
 **/*vault.yml
+**/vault*.yml
 
 # Python
 .venv/
diff --git a/README.md b/README.md
@@ -1,14 +1,17 @@
 # Ansible Collection - ukcloud.pingdom
 
-An Ansible Collection for managing SolarWinds Pingdom site monitoring. This collection has lookups for reading details from Pingdom as well as modules to create, modify and delete objects in Pingdom.
+An Ansible Collection for managing SolarWinds Pingdom site monitoring. This collection has lookups for reading details from Pingdom as well as modules to create objects in Pingdom.
 
 ## Pre-release
 
 Note this repo is at a pre-release stage. Plugin names and parameters are likely to continue to change until this reaches the first major release 1.0.0
 
 ## Using this collection
 
-Run `ansible-galaxy collection install git+https://github.com/UKCloud/ukcloud.pingdom` to install this collection.
+Use the following command to install this collection.
+
+`ansible-galaxy collection install git+https://github.com/UKCloud/ukcloud.pingdom`
+
 
 This collection uses the python `pingdompy` library, the source can be found at [https://github.com/UKCloud/pingdompy](https://github.com/UKCloud/pingdompy). This library needs to be available to the python interpreter running Ansible. One way to do this is to use pip to install Ansible and the pingdompy library.
 
@@ -66,15 +69,11 @@ timing - The timing between the check running in minutes
 
 ### uptime_checks
 
-TBC
-
-### maintenance_windows
-
-TBC
+Once this collection is installed, run `ansible-doc -t lookup ukcloud.pingdom.uptime_checks` to view the documentation for the uptime_checks lookup, which includes examples of how to call this lookup and the structure of the data returned.
 
 ## Development
 
-If you want to develop new content for this collection or improve what is already here, the easiest way to work on the collection is to clone it into one of the default [`COLLECTIONS_PATH`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths), and work on it there.
+If you want to develop new content for this collection or make any changes, the easiest way to work on the collection is to clone it into one of the default [`COLLECTIONS_PATH`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths), and edit it there.
 
 ```bash
 git clone git@github.com:UKCloud/ukcloud.pingdom.git ~/.ansible/collections/ansible_collections/ukcloud/pingdom
@@ -84,9 +83,9 @@ You can find more information in the [developer guide for collections](https://d
 
 ## Testing
 
-There are some basic testing playbooks in the /tests folder which exercise the uptime_check and maintenance_window modules. The playbooks require a Pingdom API key is passed in a variable called `vault_apikey`. Ansible Vault is one way to pass in this parameter.
+There are some basic integration test playbooks in the /tests folder which exercise the uptime_check and maintenance_window modules. The playbooks require a Pingdom API key is passed in a variable called `vault_apikey`. Ansible Vault is one way to pass in this parameter.
 
-The tests will create uptime checks and maintenance windows in Pingdom which will need to be manually deleted until `state: absent` is implemented in the modules.
+The integration tests require a valid Pingdom account and will create uptime checks and maintenance windows in Pingdom which need to be manually deleted afterwards.
 
 See [here](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#testing-collections) also.
 
diff --git a/plugins/lookup/uptime_checks.py b/plugins/lookup/uptime_checks.py
@@ -29,7 +29,9 @@
 
 EXAMPLES = """
 # Get details of all uptime checks
-- hosts: all
+- hosts: localhost
+  connection: local
+  gather_facts: No
   vars:
     all_uptime_checks: "{{ lookup('ukcloud.pingdom.uptime_checks', api_token=<token>)}}"
   tasks:
@@ -38,7 +40,9 @@
       var: all_uptime_checks
 
 # Get details of uptime checks tagged with "production"
-- hosts: all
+- hosts: localhost
+  connection: local
+  gather_facts: No
   vars:
     tagged_uptime_checks: "{{ lookup('ukcloud.pingdom.uptime_checks', api_token=<token>, tags='production')}}"
   tasks:
@@ -49,8 +53,97 @@
 
 RETURN = """
 checks:
-   description: List of checks from Pingdom
-   type: list
+    description: List of checks from Pingdom
+    type: list
+    elements: dict
+    contains:
+        created:
+            description: Unix epoch representation of when the uptime check was created.
+            returned: always
+            type: str
+            sample: '1548851044'
+        hostname:
+            description: Domain name, including sub-domain, of the target for the uptime check.
+            returned: always
+            type: str
+            sample: 'google.com'
+        id:
+            description: Unique identifier to the uptime check.
+            returned: always
+            type: str
+            sample: '1234567'
+        ipv6: false
+            description: Whether the uptime check uses ipv6 instead of ipv4.
+            returned: always
+            type: str
+            sample: 'false'
+        lastdownend: 1615034565
+            description: Unix epoch representation of the end of the last downtime period.
+            returned: Only returned if the uptime check has ever been considered down.
+            type: str
+            sample: '1548851044'
+        lastdownstart:
+            description: Unix epoch representation of the start of the last downtime period.
+            returned: Only returned if the uptime check has ever been considered down.
+            type: str
+            sample: '1548851044'
+        lasterrortime:
+            description: Unix epoch representation of when the uptime check last threw an error when it ran.
+            returned: Only returned if the uptime check has ever thrown an error when run.
+            type: str
+            sample: '1615034507'
+        lastresponsetime:
+            description: Unix epoch representation of the uptime_check response time.
+            returned: always
+            type: str
+            sample: '123'
+        lasttesttime:
+            description: Unix epoch representation of when the uptime check was last checked.
+            returned: always
+            type: str
+            sample: '1615808445'
+        maintenanceids:
+            description: Ids of all maintenance windows which cover this uptime check.
+            returned: Only returned if there are any maintenance windows which reference this uptime check.
+            type: list
+            elements: str
+            sample:
+                - '12345'
+                - '67890'
+        name:
+            description: Name of the uptime check in Pingdom.
+            returned: always
+            type: str
+            sample: 'Production host uptime check'
+        probe_filters:
+            description:
+                - List of probe filters applied to the uptime check.
+                - These limit geographically the uptime check is called from.
+            returned: Only returned when probe filters are configured for the uptime check.
+            type: list
+            elements: str
+            sample:
+                - "region: EU"
+        resolution:
+            description: Frequency the uptime check will be run, in minutes.
+            returned: always
+            type: str
+            sample: '5'
+        status: up
+            description: Whenther the uptime check is currently considered "up" or "down".
+            returned: always
+            type: str
+            sample: 'down'
+        type: http
+            description: Protocol used by the uptime check, "http" or "https".
+            returned: always
+            type: str
+            sample: 'https'
+        verify_certificate: true
+            description: Whether to consider the validity of the endpoints ssl certificate in the uptime check status.
+            returned: always
+            type: str
+            sample: 'true'
 """
 
 
@@ -62,15 +155,11 @@ class LookupModule(LookupBase):
     def run(self, terms, variables=None, **kwargs):
         """ main entrypoint for the lookup """
         display = Display()
-        display.debug(f"DEBUG: lookup uptime_checks called with terms = {terms}")
-        display.debug(f"DEBUG: lookup uptime_checks called with kwargs = {kwargs}")
 
         api_token = kwargs.get("api_token")
-        display.vvv(f"DEBUG: Got api_token of {api_token}")
-        tags = kwargs.get("tags")
-        display.vvv(f"DEBUG: Got tags of {tags}")
         if not api_token:
             raise AnsibleError(message="'api_token' must be passed to the ukcloud.pingdom.uptime_checks lookup.")
+        tags = kwargs.get("tags")
         data = get_checks(api_token, tags)
 
         return [data]
