Merge pull request #54 from LBGarber/add-inventory-plugin

Add Instance Inventory plugin

Author: 0xch4z

.mypy.ini

@@ -4,4 +4,4 @@ disallow_untyped_defs = True
 disallow_untyped_calls = True
 disallow_incomplete_defs = True
 disallow_untyped_decorators = True
-no_strict_optional = True
+no_strict_optional = True

Makefile

@@ -15,12 +15,19 @@ install: clean build
 
 lint:
 	pylint plugins
-	mypy plugins
+
+	mypy plugins/modules
+	mypy plugins/inventory
 
 gendocs:
 	mkdir -p $(DOCS_PATH)
-	rm -f $(DOCS_PATH)/*
-	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH) plugins/modules/*.py
+
+	rm -rf $(DOCS_PATH)/*
+
+	mkdir -p $(DOCS_PATH)/modules $(DOCS_PATH)/inventory
+
+	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/modules plugins/modules/*.py
+	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/inventory plugins/inventory/*.py
 
 integration-test: $(INTEGRATION_CONFIG)
 	ansible-test integration $(TEST_ARGS)
@@ -32,4 +39,4 @@ $(INTEGRATION_CONFIG):
 	  echo "LINODE_API_TOKEN must be set"; \
 	  exit 1; \
 	fi
-	echo "---\napi_token: $(LINODE_API_TOKEN)" >> $(INTEGRATION_CONFIG)
+	echo "api_token: $(LINODE_API_TOKEN)" >> $(INTEGRATION_CONFIG)

README.md

@@ -19,17 +19,22 @@ PEP440 is the schema used to describe the versions of Ansible.
 ### Modules
 Name | Description
 --- | ---
-[linode.cloud.firewall](https://github.com/linode/ansible_linode/blob/master/docs/firewall.rst)|Create and destroy Firewalls.
-[linode.cloud.firewall_info](https://github.com/linode/ansible_linode/blob/master/docs/firewall_info.rst)|Gather info about an existing Firewall.
-[linode.cloud.instance](https://github.com/linode/ansible_linode/blob/master/docs/instance.rst)|Create and destroy Linodes.
-[linode.cloud.instance_info](https://github.com/linode/ansible_linode/blob/master/docs/instance_info.rst)|Gather info about an existing Linode instance.
-[linode.cloud.nodebalancer](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer.rst)|Create, destroy, and configure NodeBalancers.
-[linode.cloud.nodebalancer_info](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer_info.rst)|Gather info about an existing NodeBalancer.
-[linode.cloud.object_cluster_info](https://github.com/linode/ansible_linode/blob/master/docs/object_cluster_info.rst)|Gather info about Object Storage clusters.
-[linode.cloud.object_keys](https://github.com/linode/ansible_linode/blob/master/docs/object_keys.rst)|Create and destroy Object Storage keys.
-[linode.cloud.vlan_info](https://github.com/linode/ansible_linode/blob/master/docs/vlan_info.rst)|Gather info about an existing Linode VLAN.
-[linode.cloud.volume](https://github.com/linode/ansible_linode/blob/master/docs/volume.rst)|Create, destroy, and attach Linode volumes.
-[linode.cloud.volume_info](https://github.com/linode/ansible_linode/blob/master/docs/volume_info.rst)|Gather info about an existing Linode volume.
+[linode.cloud.firewall](https://github.com/linode/ansible_linode/blob/master/docs/modules/firewall.rst)|Create and destroy Firewalls.
+[linode.cloud.firewall_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/firewall_info.rst)|Gather info about an existing Firewall.
+[linode.cloud.instance](https://github.com/linode/ansible_linode/blob/master/docs/modules/instance.rst)|Create and destroy Linodes.
+[linode.cloud.instance_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/instance_info.rst)|Gather info about an existing Linode instance.
+[linode.cloud.nodebalancer](https://github.com/linode/ansible_linode/blob/master/docs/modules/nodebalancer.rst)|Create, destroy, and configure NodeBalancers.
+[linode.cloud.nodebalancer_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/nodebalancer_info.rst)|Gather info about an existing NodeBalancer.
+[linode.cloud.object_cluster_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/object_cluster_info.rst)|Gather info about Object Storage clusters.
+[linode.cloud.object_keys](https://github.com/linode/ansible_linode/blob/master/docs/modules/object_keys.rst)|Create and destroy Object Storage keys.
+[linode.cloud.vlan_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/vlan_info.rst)|Gather info about an existing Linode VLAN.
+[linode.cloud.volume](https://github.com/linode/ansible_linode/blob/master/docs/modules/volume.rst)|Create, destroy, and attach Linode volumes.
+[linode.cloud.volume_info](https://github.com/linode/ansible_linode/blob/master/docs/modules/volume_info.rst)|Gather info about an existing Linode volume.
+
+### Inventory
+Name | Description
+--- | ---
+[linode.cloud.instance](https://github.com/linode/ansible_linode/blob/master/docs/inventory/instance.rst)|Reads instance inventories from Linode.
 
 <!--end collection content-->
 

docs/inventory/instance.rst

@@ -0,0 +1,148 @@
+.. _instance_module:
+
+
+instance
+========
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+
+Reads instance inventories from Linode.
+
+Uses a YAML configuration file that ends with linode.(yml|yaml).
+
+Linode labels are used by default as the hostnames.
+
+The default inventory groups are built from groups (deprecated by Linode) and not tags.
+
+
+
+Requirements
+------------
+The below requirements are needed on the host that executes this module.
+
+- python >= 2.7
+- linode_api4 >= 2.0.0
+
+
+
+Parameters
+----------
+
+  plugin (True, any, None)
+    marks this as an instance of the 'linode' plugin
+
+
+  api_token (True, any, None)
+    The Linode account personal access token.
+
+
+  regions (optional, list, [])
+    Populate inventory with instances in this region.
+
+
+  tags (optional, list, [])
+    Populate inventory only with instances which have at least one of the tags listed here.
+
+
+  types (optional, list, [])
+    Populate inventory with instances with this type.
+
+
+  strict (optional, bool, False)
+    If ``yes`` make invalid entries a fatal error, otherwise skip and continue.
+
+    Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
+
+
+  compose (optional, dict, {})
+    Create vars from jinja2 expressions.
+
+
+  groups (optional, dict, {})
+    Add hosts to group based on Jinja2 conditionals.
+
+
+  keyed_groups (optional, list, [])
+    Add hosts to group based on the values of a variable.
+
+
+  use_extra_vars (optional, bool, False)
+    Merge extra vars into the available variables for composition (highest precedence).
+
+
+  leading_separator (optional, boolean, True)
+    Use in conjunction with keyed_groups.
+
+    By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
+
+    This is because the default prefix is "" and the default separator is "_".
+
+    Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+
+    If the group name is derived from a mapping the separator is still used to concatenate the items.
+
+    To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
+
+
+
+
+
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+    
+    # Minimal example. `LINODE_API_TOKEN` is exposed in environment.
+    plugin: linode.cloud.instance
+
+    # Example with regions, types, groups and access token
+    plugin: linode.cloud.instance
+    api_token: foobar
+    regions:
+      - eu-west
+    types:
+      - g5-standard-2
+
+    # Example with keyed_groups, groups, and compose
+    plugin: linode.cloud.instance
+    api_token: foobar
+    keyed_groups:
+      - key: tags
+        separator: ''
+      - key: region
+        prefix: region
+    groups:
+      webservers: "'web' in (tags|list)"
+      mailservers: "'mail' in (tags|list)"
+    compose:
+      ansible_port: 2222
+
+
+
+
+
+
+Status
+------
+
+
+
+
+
+Authors
+~~~~~~~
+
+- Luke Murphy (@decentral1se)
+- Lena Garber (@LBGarber)
+