diff options
author | Abhijeet Kasurde <akasurde@redhat.com> | 2020-08-19 01:26:43 +0530 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-08-18 15:56:43 -0400 |
commit | 4f993922c87a6f12821f40c460750471bd6ee1e7 (patch) | |
tree | f587982cffcf1806fa6e9249197dce48a839d8a8 /examples | |
parent | f79a7c558574a44016d2ff978aaddf00f241a08c (diff) | |
download | ansible-4f993922c87a6f12821f40c460750471bd6ee1e7.tar.gz |
Add documentation about info/facts module development (#71250)
Fixes: #40151
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
Diffstat (limited to 'examples')
-rw-r--r-- | examples/scripts/my_test.py | 134 | ||||
-rw-r--r-- | examples/scripts/my_test_facts.py | 96 | ||||
-rw-r--r-- | examples/scripts/my_test_info.py | 111 |
3 files changed, 341 insertions, 0 deletions
diff --git a/examples/scripts/my_test.py b/examples/scripts/my_test.py new file mode 100644 index 0000000000..3363fc1aa5 --- /dev/null +++ b/examples/scripts/my_test.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python + +# Copyright: (c) 2018, Terry Jones <terry.jones@example.org> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = r''' +--- +module: my_test + +short_description: This is my test module + +# If this is part of a collection, you need to use semantic versioning, +# i.e. the version is of the form "2.5.0" and not "2.4". +version_added: "1.0.0" + +description: This is my longer description explaining my test module. + +options: + name: + description: This is the message to send to the test module. + required: true + type: str + new: + description: + - Control to demo if the result of this module is changed or not. + - Parameter description can be a list as well. + required: false + type: bool +# Specify this value according to your collection +# in format of namespace.collection.doc_fragment_name +extends_documentation_fragment: + - my_namespace.my_collection.my_doc_fragment_name + +author: + - Your Name (@yourGitHubHandle) +''' + +EXAMPLES = r''' +# Pass in a message +- name: Test with a message + my_namespace.my_collection.my_test: + name: hello world + +# pass in a message and have changed true +- name: Test with a message and changed output + my_namespace.my_collection.my_test: + name: hello world + new: true + +# fail the module +- name: Test failure of the module + my_namespace.my_collection.my_test: + name: fail me +''' + +RETURN = r''' +# These are examples of possible return values, and in general should use other names for return values. +original_message: + description: The original name param that was passed in. + type: str + returned: always + sample: 'hello world' +message: + description: The output message that the test module generates. + type: str + returned: always + sample: 'goodbye' +''' + +from ansible.module_utils.basic import AnsibleModule + + +def run_module(): + # define available arguments/parameters a user can pass to the module + module_args = dict( + name=dict(type='str', required=True), + new=dict(type='bool', required=False, default=False) + ) + + # seed the result dict in the object + # we primarily care about changed and state + # changed is if this module effectively modified the target + # state will include any data that you want your module to pass back + # for consumption, for example, in a subsequent task + result = dict( + changed=False, + original_message='', + message='' + ) + + # the AnsibleModule object will be our abstraction working with Ansible + # this includes instantiation, a couple of common attr would be the + # args/params passed to the execution, as well as if the module + # supports check mode + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True + ) + + # if the user is working with this module in only check mode we do not + # want to make any changes to the environment, just return the current + # state with no modifications + if module.check_mode: + module.exit_json(**result) + + # manipulate or modify the state as needed (this is going to be the + # part where your module will do what it needs to do) + result['original_message'] = module.params['name'] + result['message'] = 'goodbye' + + # use whatever logic you need to determine whether or not this module + # made any modifications to your target + if module.params['new']: + result['changed'] = True + + # during the execution of the module, if there is an exception or a + # conditional state that effectively causes a failure, run + # AnsibleModule.fail_json() to pass in the message and the result + if module.params['name'] == 'fail me': + module.fail_json(msg='You requested this to fail', **result) + + # in the event of a successful module execution, you will want to + # simple AnsibleModule.exit_json(), passing the key/value results + module.exit_json(**result) + + +def main(): + run_module() + + +if __name__ == '__main__': + main() diff --git a/examples/scripts/my_test_facts.py b/examples/scripts/my_test_facts.py new file mode 100644 index 0000000000..8484e3c374 --- /dev/null +++ b/examples/scripts/my_test_facts.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python + +# Copyright: (c) 2020, Your Name <YourName@example.org> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = r''' +--- +module: my_test_facts + +short_description: This is my test facts module + +version_added: "1.0.0" + +description: This is my longer description explaining my test facts module. + +author: + - Your Name (@yourGitHubHandle) +''' + +EXAMPLES = r''' +- name: Return ansible_facts + my_namespace.my_collection.my_test_facts: +''' + +RETURN = r''' +# These are examples of possible return values, and in general should use other names for return values. +ansible_facts: + description: Facts to add to ansible_facts. + returned: always + type: dict + contains: + foo: + description: Foo facts about operating system. + type: str + returned: when operating system foo fact is present + sample: 'bar' + answer: + description: + - Answer facts about operating system. + - This description can be a list as well. + type: str + returned: when operating system answer fact is present + sample: '42' +''' + +from ansible.module_utils.basic import AnsibleModule + + +def run_module(): + # define available arguments/parameters a user can pass to the module + module_args = dict() + + # seed the result dict in the object + # we primarily care about changed and state + # changed is if this module effectively modified the target + # state will include any data that you want your module to pass back + # for consumption, for example, in a subsequent task + result = dict( + changed=False, + ansible_facts=dict(), + ) + + # the AnsibleModule object will be our abstraction working with Ansible + # this includes instantiation, a couple of common attr would be the + # args/params passed to the execution, as well as if the module + # supports check mode + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True + ) + + # if the user is working with this module in only check mode we do not + # want to make any changes to the environment, just return the current + # state with no modifications + if module.check_mode: + module.exit_json(**result) + + # manipulate or modify the state as needed (this is going to be the + # part where your module will do what it needs to do) + result['ansible_facts'] = { + 'foo': 'bar', + 'answer': '42', + } + # in the event of a successful module execution, you will want to + # simple AnsibleModule.exit_json(), passing the key/value results + module.exit_json(**result) + + +def main(): + run_module() + + +if __name__ == '__main__': + main() diff --git a/examples/scripts/my_test_info.py b/examples/scripts/my_test_info.py new file mode 100644 index 0000000000..7db3edda28 --- /dev/null +++ b/examples/scripts/my_test_info.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python + +# Copyright: (c) 2020, Your Name <YourName@example.org> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = r''' +--- +module: my_test_info + +short_description: This is my test info module + +version_added: "1.0.0" + +description: This is my longer description explaining my test info module. + +options: + name: + description: This is the message to send to the test module. + required: true + type: str + +author: + - Your Name (@yourGitHubHandle) +''' + +EXAMPLES = r''' +# Pass in a message +- name: Test with a message + my_namespace.my_collection.my_test_info: + name: hello world +''' + +RETURN = r''' +# These are examples of possible return values, and in general should use other names for return values. +original_message: + description: The original name param that was passed in. + type: str + returned: always + sample: 'hello world' +message: + description: The output message that the test module generates. + type: str + returned: always + sample: 'goodbye' +my_useful_info: + description: The dictionary containing information about your system. + type: dict + returned: always + sample: { + 'foo': 'bar', + 'answer': 42, + } +''' + +from ansible.module_utils.basic import AnsibleModule + + +def run_module(): + # define available arguments/parameters a user can pass to the module + module_args = dict( + name=dict(type='str', required=True), + ) + + # seed the result dict in the object + # we primarily care about changed and state + # changed is if this module effectively modified the target + # state will include any data that you want your module to pass back + # for consumption, for example, in a subsequent task + result = dict( + changed=False, + original_message='', + message='', + my_useful_info={}, + ) + + # the AnsibleModule object will be our abstraction working with Ansible + # this includes instantiation, a couple of common attr would be the + # args/params passed to the execution, as well as if the module + # supports check mode + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True + ) + + # if the user is working with this module in only check mode we do not + # want to make any changes to the environment, just return the current + # state with no modifications + if module.check_mode: + module.exit_json(**result) + + # manipulate or modify the state as needed (this is going to be the + # part where your module will do what it needs to do) + result['original_message'] = module.params['name'] + result['message'] = 'goodbye' + result['my_useful_info'] = { + 'foo': 'bar', + 'answer': 42, + } + # in the event of a successful module execution, you will want to + # simple AnsibleModule.exit_json(), passing the key/value results + module.exit_json(**result) + + +def main(): + run_module() + + +if __name__ == '__main__': + main() |