FEATURE: Ansible module for managing boxes

An Ansible module for returning managing Stacki boxes. The OS of the box can be modified only if no hosts are assigned to the box. Changing the OS of the box involves removing the existing box and re-adding it with the new OS. All enabled pallets, carts, and repos will need to be re-enabled.

The module takes three parameters:
`name` - The name of the box to manage
`os` - The OS of the box to create. Defaults to the OS of the frontend.
`state` - If present, then a box will be added if it doesn't exist. If the box does already exist but the OS is different, the box will be removed and re-added with the updated OS. If absent, then the box will be removed (if it exists).

Example playbook:
```
---
- hosts: localhost
  tasks:
    - name: Add a box
      stacki_box:
        name: test
        os: sles
      register: result

    - name: Add box output
      debug:
        var: result

    - name: Remove a box
      stacki_box:
        name: test
        state: absent
      register: result

    - name: Remove box output
      debug:
        var: result
```

Output of the debug commands, showing the structure of the data returned:
```

TASK [Add box output] **************************************************************************************************
ok: [localhost] => {
    "result": {
        "changed": true,
        "failed": false
    }
}

TASK [Remove box output] ***********************************************************************************************
ok: [localhost] => {
    "result": {
        "changed": true,
        "failed": false
    }
}
```

Author: caladd

common/src/stack/ansible/plugins/modules/stacki_box.py

@@ -0,0 +1,127 @@
+# @copyright@
+# Copyright (c) 2006 - 2020 Teradata
+# All rights reserved. Stacki(r) v5.x stacki.com
+# https://github.com/Teradata/stacki/blob/master/LICENSE.txt
+# @copyright@
+
+DOCUMENTATION = """
+module: stacki_box
+short_description: Manage Stacki boxes
+description:
+  - Add, edit, and remove Stacki boxes
+  - The OS of the box can be modified only if no hosts are assigned to the box.
+  - Changing the OS of the box involves removing the existing box and re-adding it with the new OS. All enabled pallets, carts, and repos will need to be re-enabled.
+
+options:
+  name:
+    description:
+      - The name of the box to manage
+    required: true
+    type: str
+
+  os:
+    description:
+      - The OS of the box to create
+    required: false
+    type: str
+    default: OS of frontend
+
+  state:
+    description:
+      - If present, then a box will be added if it doesn't exist
+      - If present and the box exists but the OS is different, the box will be removed and re-added with the updated OS.
+      - If absent, then the box will be removed
+    type: str
+    choices: [ absent, present ]
+    default: present
+"""
+
+EXAMPLES = """
+- name: Add a box default
+  stacki_box:
+    name: foo
+
+- name: Remove a box
+  stacki_box:
+    name: foo
+    state: absent
+"""
+
+RETURN = """ # """
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.stacki import run_stack_command, StackCommandError
+
+
+def main():
+	# Define the arguments for this module
+	argument_spec = dict(
+		name=dict(type="str", required=True),
+		os=dict(type="str", required=False),
+		state=dict(type="str", default="present", choices=["absent", "present"])
+	)
+
+	# Create our module object
+	module = AnsibleModule(
+		argument_spec=argument_spec,
+		supports_check_mode=True
+	)
+
+	# Initialize a blank result
+	result = {
+		"changed": False
+	}
+
+	# Bail if the user is just checking syntax of their playbook
+	if module.check_mode:
+		module.exit_json(**result)
+
+	# Fetch our box info from Stacki
+	try:
+		boxes = run_stack_command("list.box", [module.params["name"]])
+	except StackCommandError as e:
+		# If box doesn't exist, it will raise an error
+		boxes = []
+
+	if len(boxes) > 1:
+		# No more than one box should match
+		module.fail_json(msg="error - more than one box matches name", **result)
+
+	try:
+		# Are we adding or removing?
+		if module.params["state"] == "present":
+			args = [module.params["name"]]
+			if module.params["os"]:
+				args.append("os="+module.params["os"])
+
+			if len(boxes) == 0:
+				# Add a new box
+				args = [module.params["name"]]
+				if module.params["os"]:
+					args.append("os="+module.params["os"])
+
+				run_stack_command("add.box", args)
+				result["changed"] = True
+
+			elif module.params["os"] and module.params["os"] != boxes[0]["os"]:
+				# Try to make the OS match. Might throw an error if the box has hosts attached.
+				run_stack_command("remove.box", [module.params["name"]])
+				run_stack_command("add.box", args)
+				result["changed"] = True
+
+		else:
+			# Only remove a box that actually exists
+			if len(boxes):
+				run_stack_command("remove.box", [module.params["name"]])
+				result["changed"] = True
+
+	except StackCommandError as e:
+		# Fetching the data failed
+		module.fail_json(msg=e.message, **result)
+
+	# Return our data
+	module.exit_json(**result)
+
+
+if __name__ == "__main__":
+	main()

test-framework/test-suites/integration/tests/ansible/test_stacki_box.py

@@ -0,0 +1,95 @@
+import json
+
+
+class TestStackiBox:
+	def test_add_box(self, host, host_os, run_ansible_module):
+		# Add the box
+		result = run_ansible_module("stacki_box", name="test")
+
+		assert result.status == "CHANGED"
+		assert result.data["changed"] == True
+
+		# Check that it is there now
+		result = host.run("stack list box test output-format=json")
+		assert result.rc == 0
+		assert json.loads(result.stdout) == [
+			{
+				"name": "test",
+				"os": host_os,
+				"pallets": "",
+				"carts": "",
+				"repos": "",
+			}
+		]
+
+		# Test idempotency by adding again
+		result = run_ansible_module("stacki_box", name="test")
+
+		assert result.status == "SUCCESS"
+		assert result.data["changed"] == False
+
+	def test_change_os(self, host, host_os, run_ansible_module):
+		# Add the box
+		result = run_ansible_module("stacki_box", name="test")
+
+		assert result.status == "CHANGED"
+		assert result.data["changed"] == True
+
+		# Check that it is there now
+		result = host.run("stack list box test output-format=json")
+		assert result.rc == 0
+		assert json.loads(result.stdout) == [
+			{
+				"name": "test",
+				"os": host_os,
+				"pallets": "",
+				"carts": "",
+				"repos": "",
+			}
+		]
+
+		# Now change to OS
+		result = run_ansible_module("stacki_box", name="test", os="ubuntu")
+
+		assert result.status == "CHANGED"
+		assert result.data["changed"] == True
+
+		# Check that the OS is changed
+		result = host.run("stack list box test output-format=json")
+		assert result.rc == 0
+		assert json.loads(result.stdout) == [
+			{
+				"name": "test",
+				"os": "ubuntu",
+				"pallets": "",
+				"carts": "",
+				"repos": "",
+			}
+		]
+
+	def test_remove_box(self, add_box, host, run_ansible_module):
+		# Remove the box
+		result = run_ansible_module("stacki_box", name="test", state="absent")
+
+		assert result.status == "CHANGED"
+		assert result.data["changed"] == True
+
+		# And confirm it is gone
+		result = host.run("stack list box test")
+		assert result.rc == 255
+		assert "not a valid box" in result.stderr
+
+		# Test idempotency by removing it again
+		result = run_ansible_module("stacki_box", name="test", state="absent")
+
+		assert result.status == "SUCCESS"
+		assert result.data["changed"] == False
+
+	def test_bad_name(self, add_box, run_ansible_module):
+		result = run_ansible_module("stacki_box", name="%", state="absent")
+
+		assert result.status == "FAILED!"
+		assert result.data["changed"] == False
+
+		assert "error" in result.data["msg"]
+		assert "more than one box matches name" in result.data["msg"]