def main():

    module = AnsibleModule(
        # not checking because of daisy chain to file module
        argument_spec=dict(
            src=dict(type='path'),
            original_basename=dict(type='str'),  # used to handle 'dest is a directory' via template, a slight hack
            content=dict(type='str', no_log=True),
            dest=dict(type='path', required=True),
            backup=dict(type='bool', default=False),
            force=dict(type='bool', default=True, aliases=['thirsty']),
            validate=dict(type='str'),
            directory_mode=dict(type='raw'),
            remote_src=dict(type='bool'),
            local_follow=dict(type='bool'),
            checksum=dict(),
        ),
        add_file_common_args=True,
        supports_check_mode=True,
    )

    src = module.params['src']
    b_src = to_bytes(src, errors='surrogate_or_strict')
    dest = module.params['dest']
    b_dest = to_bytes(dest, errors='surrogate_or_strict')
    backup = module.params['backup']
    force = module.params['force']
    original_basename = module.params.get('original_basename', None)
    validate = module.params.get('validate', None)
    follow = module.params['follow']
    mode = module.params['mode']
    remote_src = module.params['remote_src']
    checksum = module.params['checksum']

    if not os.path.exists(b_src):
        module.fail_json(msg="Source %s not found" % (src))
    if not os.access(b_src, os.R_OK):
        module.fail_json(msg="Source %s not readable" % (src))
    if os.path.isdir(b_src):
        module.fail_json(msg="Remote copy does not support recursive copy of directory: %s" % (src))
 

以上是copy模組例子

模組是一個獨立的, 可以複用的指令碼, 它可以被anisible API, Ansible 或者ansible-playbook使用.   在模組退出之前, 它通過輸出一個json字串到標準輸出從而反饋資訊給ansible.  你可以用任何一種語言去寫一個模組. 寫好的模組可以放在ANSIBLE_LIBRARY或者--module-path目錄下. 通常情況下playbook的目錄下的library目錄也可以做為模組的預設目錄.

1. 模組的基本開發模式

　　一個簡單的模組, 之所以用這個作為例子, 是因為你可以用任何語言去開發自己的模組, 我們需要了解模組最基本的開發模式

#!/usr/bin/python

import datetime
import json

date = str(datetime.datetime.now())
print json.dumps({
    "time" : date
})

　　模組測試

git clone git://github.com/ansible/ansible.git --recursive
source ansible/hacking/env-setup

ansible/hacking/test-module -m ./timetest.py

　　模組引數

 　　ansible會自動的把引數儲存到一個引數檔案中, 所以我們必須讀取並分析這個檔案. 這個引數檔案只是一個字串, 所以任何形式的引數都是合法的.  

#!/usr/bin/python

# import some python modules that we'll use.  These are all
# available in Python's core

import datetime
import sys
import json
import os
import shlex

# read the argument string from the arguments file
args_file = sys.argv[1]
args_data = file(args_file).read()

arguments = shlex.split(args_data)
for arg in arguments:

    # ignore any arguments without an equals in it
    if "=" in arg:

        (key, value) = arg.split("=")
        if key == "time":


            rc = os.system("date -s \"%s\"" % value)

            if rc != 0:
                print json.dumps({
                    "failed" : True,
                    "msg"    : "failed setting the time"
                })
                sys.exit(1)

            date = str(datetime.datetime.now())
            print json.dumps({
                "time" : date,
                "changed" : True
            })
            sys.exit(0)


date = str(datetime.datetime.now())
print json.dumps({
    "time" : date
})
測試模組
ansible/hacking/test-module -m ./timetest.py -a "time=\"March 14 12:23\""

　　二進位制模組

　　二進位制模組的支援會在ansible2.2中加入,  當ansible發現是二進位制模組是, 它會提供一個json檔案argv[1]來儲存引數.

　　提供facts的模組

　　setup模組可以提供很多系統相關的變數, 然而使用者不修改系統模組也可以新增自定義變數, 只需要在模組的返回值中加入ansible_facts這個鍵值. 例如:

{
    "changed" : True,
    "rc" : 5,
    "ansible_facts" : {
        "leptons" : 5000,
        "colors" : {
            "red"   : "FF0000",
            "white" : "FFFFFF"
        }
    }
}

開發一個site_facts的模組並且在所有的playbook之前呼叫是一個較好的習慣, 

2. 通用的模組樣板

　　如果你使用python來開發自定義模組, ansible提供了很多強大的快捷方式. 模組仍然儲存在一個檔案當中, 但是我們不需要再去處理引數檔案. 最好的學習方法是去學習ansible的核心模組.

from ansible.module_utils.basic import AnsibleModule
if __name__ == '__main__':
    main()

Note: 對於ansible2.1來說, 上面的匯入已經不能工作, 必須使用from ansible.module_utils.basic import *

def main():
    module = AnsibleModule(
        argument_spec = dict(
            state     = dict(default='present', choices=['present', 'absent']),
            name      = dict(required=True),
            enabled   = dict(required=True, type='bool'),
            something = dict(aliases=['whatever'])
        )
    )
AnsibleModule 提供和很多通用的函式來處理返回值, 分析引數並允許你檢查輸入
成功返回

module.exit_json(changed=True, something_else=12345)
失敗退出

module.fail_json(msg="Something fatal happened")

還有很多其他的基礎功能, 課參看lib/ansible/module_utils/basic.py 

　　check模式

　　模組支援check模式. 如果使用者在check模式下執行ansible, 模組會去嘗試預判change是否發生. 如果想定義一個check模組, 使用者必須在初始化模組的時候設定supports_check_mode=True

module = AnsibleModule(
    argument_spec = dict(...),
    supports_check_mode=True
)

if module.check_mode:
    # Check if any changes would be made but don't actually make those changes
    module.exit_json(changed=check_if_system_state_would_be_changed())
作為模組的開發者, 你有責任去保證在check模式下沒有系統狀態被改變?
Remember that, as module developer, you are responsible for ensuring that no system state is altered when the user enables check mode.

如果你的模組不支援check模式, 而使用者卻在check模式下執行ansible, 你的模組會被自動跳過

　　在模組中永遠不要使用"print "some status message"".  因為在ansible中輸出被假定為一個可用的json.

　　Modules must not output anything on standard error, because the system will merge standard out with standard error and prevent the JSON from parsing. Capturing standard error and returning it as a variable in the JSON on standard out is fine, and is, in fact, how the command module is implemented.

ANSIBLE_KEEP_REMOTE_FILES 這個引數會保留在遠端伺服器上執行的python指令碼. 可以用來debug.