ansible modules开发（一）

一模块说明

官方是否有提供的类似功能模块？
可从下面两个连接确定官方提供的模块，以免重复造轮子
官方已发布的模块 http://docs.ansible.com/ansible/modules.html
官方正在开发的模块 https://github.com/ansible/ansible/labels/module
你需要开发一个action 插件么？
action插件是在ansible主机上运行，而不是在目标主机上运行的。对于类似file/copy/template功能的模块，在模块执行前需要在ansible主机上做一些操作的。

- 模块是传送到目标主机上运行的。

- 模块的返回值必须是json dumps的字符串。

1 模块执行的过程

首先，将模块文件读入内存，然后添加传递给模块的参数，最后将模块中所需要的类添加到内存，由zipfile压缩后，再由base64进行编码，写入到模版文件内。

通过默认的连接方式，一般是ssh。ansible通过ssh连接到远程主机，创建临时目录，并关闭连接。然后将打开另外一个ssh连接，将模版文件以sftp方式传送到刚刚创建的临时目录中，写完后关闭连接。然后打开一个ssh连接将任务对象赋予可执行权限，执行成功后关闭连接。

最后，ansible将打开第三个连接来执行模块，并删除临时目录及其所有内容。模块的结果是从标准输出stdout中获取json格式的字符串。ansible将解析和处理此字符串。如果有任务是异步控制执行的，ansible将在模块完成之前关闭第三个连接，并且返回主机后，在规定的时间内检查任务状态，直到模块完成或规定的时间超时。

使用了管道连接后，与远程主机只有一个连接，命令通过数据流的方式发送执行。

配置方式

vim /etc/ansible/ansible.cfg

pipelining = True

执行过程

Ansible提供了许多模块实用程序，它们提供了在开发自己的模块时可以使用的辅助功能。 basic.py模块为程序提供访问Ansible库的主要入口点，所有Ansible模块必须至少从basic.py导入：

 from ansible.module_utils.basic import *

其他模块工具

a10.py - Utilities used by the a10_server module to manage A10 Networks devices.

api.py - Adds shared support for generic API modules.

aos.py - Module support utilities for managing Apstra AOS Server.

asa.py - Module support utilities for managing Cisco ASA network devices.

azure_rm_common.py - Definitions and utilities for Microsoft Azure Resource Manager template deployments.

basic.py - General definitions and helper utilities for Ansible modules.

cloudstack.py - Utilities for CloudStack modules.

database.py - Miscellaneous helper functions for PostGRES and MySQL

docker_common.py - Definitions and helper utilities for modules working with Docker.

ec2.py - Definitions and utilities for modules working with Amazon EC2

eos.py - Helper functions for modules working with EOS networking devices.

f5.py - Helper functions for modules working with F5 networking devices.

facts.py - Helper functions for modules that return facts.

gce.py - Definitions and helper functions for modules that work with Google Compute Engine resources.

ios.py - Definitions and helper functions for modules that manage Cisco IOS networking devices

iosxr.py - Definitions and helper functions for modules that manage Cisco IOS-XR networking devices

ismount.py - Contains single helper function that fixes os.path.ismount

junos.py - Definitions and helper functions for modules that manage Junos networking devices

known_hosts.py - utilities for working with known_hosts file

mysql.py - Allows modules to connect to a MySQL instance

netapp.py - Functions and utilities for modules that work with the NetApp storage platforms.

netcfg.py - Configuration utility functions for use by networking modules

netcmd.py - Defines commands and comparison operators for use in networking modules

network.py - Functions for running commands on networking devices

nxos.py - Contains definitions and helper functions specific to Cisco NXOS networking devices

openstack.py - Utilities for modules that work with Openstack instances.

openswitch.py - Definitions and helper functions for modules that manage OpenSwitch devices

powershell.ps1 - Utilities for working with Microsoft Windows clients

pycompat24.py - Exception workaround for Python 2.4.

rax.py - Definitions and helper functions for modules that work with Rackspace resources.

redhat.py - Functions for modules that manage Red Hat Network registration and subscriptions

service.py - Contains utilities to enable modules to work with Linux services (placeholder, not in use).

shell.py - Functions to allow modules to create shells and work with shell commands

six/init.py - Bundled copy of the Six Python library to aid in writing code compatible with both Python 2 and Python 3.

splitter.py - String splitting and manipulation utilities for working with Jinja2 templates

urls.py - Utilities for working with http and https requests

vca.py - Contains utilities for modules that work with VMware vCloud Air

vmware.py - Contains utilities for modules that work with VMware vSphere VMs

vyos.py - Definitions and functions for working with VyOS networking

二构建一个简单的模块

1 基本步骤

1）创建目录

将这个模块放在library目录下，命名为remote_reach.py
可以使用 ANSIBLE_LIBRARY环境变量来指定模块的存放位置。也可以在playbook当前目录下创建library目录

2）创建模块

#!/usr/bin/python env

# coding:utf-8

def can_reach(module,host):

    ping_path =  module.get_bin_path('ping', required=True)

    args = [ping_path, '-c 4',host]

    (rc,stdout,stderr) = module.run_command(args)

    return rc == 0

def main():

    module = AnsibleModule(

        argument_spec=dict(

            host = dict(required=True,type='str'),

        ),

        supports_check_mode=True,

    )

    if module.check_mode:

        module.exit_json(changed=False)

    host = module.params['host']

    if can_reach(module,host):

        module.exit_json(changed=True)

    else:

        msg = 'Could not reach %s' %(host)

        module.fail_json(msg=msg)

from ansible.module_utils.basic import *

if __name__ == '__main__':

    main()

3）编写yaml文件使用模块　

编写yaml文件使用这个模块

---

- name: test remote_copy module

  hosts: webserver01

  gather_facts: false

  tasks:

    - name: do a remote host

      remote_copy: host=172.20.1.100

4）测试模块　

可以使用test-module.py 进行模块测试

5）执行这个yaml文件

ansible-playbook remote_copy.yml   # 执行这个yaml

2 module提供facts数据

与作为模块退出的一部分返回的数据类似，模块也可以直接创建fact数据，通过名为ansible_facts键返回数据到主机。无需为任务register一个变量来获取数值。

remote_facts = {'rc_source': module.params['source'], 'rc_dest': module.params['dest'] } 
module.exit_json(changed=True, ansible_facts=remote_facts)

在playbook中添加查看fact的任务

- name: show a fact

     debug: var=rc_dest

3 检查模式

模块可以选择支持检查模式http://docs.ansible.com/ansible/playbooks_checkmode.html。如果用户在检查模式下运行可执行安全性，则模块应该尝试预测和报告是否发生更改，但实际上不会进行任何更改（不支持检查模式的模块也不会采取任何动作，但只是不会报告其可能的更改）。

对于您的模块支持检查模式，您必须在实例化AnsibleModule对象时传递supports_check_mode = True。当启用检查模式时，AnsibleModule.check_mode属性将计算为True。例如：

module = AnsibleModule( argument_spec = dict( source=dict(required=True, type='path'), dest=dict(required=True, type='path') ), supports_check_mode=True ) 

if not module.check_mode:

    shutil.copy(module.params['source'], module.params['dest'])

在进行检查模式的时候，不执行拷贝动作，看下列运行状态。

 ansible-playbook remote_copy.yml -C

三添加module文档说明

所有模块必须按以下顺序定义以下部分：

ANSIBLE_METADATA
DOCUMENTATION
EXAMPLES
RETURNS
Python imports

1. 定义ANSIBLE_METADATA，该变量描述有关其他工具使用的模块的信息

ANSIBLE_METADATA = {'metadata_version': '1.0',

                    'status': ['preview'],

                    'supported_by': 'community'}

2. 定义DOCUMENTATION，该变量描述模块的描述信息，参数，作者和许可信息。

DOCUMENTATION = '''

---

module: remote_copy

version_added: "2.3"

short_description: Copy a file on the remote host

description:

    - The remote_copy module copies a file on the remote host from a given source to a provided destination. 

options:

    source:

        description:

          - Path to a file on the source file on the remote host

        required: true

     dest:

        description:

          - Path to the destination on the remote host for the copy

        required: true

author:

        - "Lework" '''

3. 定义EXAMPLES，该变量用来描述模块的一个或多个示例使用

EXAMPLES = ''' 

# Example from Ansible Playbooks 

- name: backup a config file

    remote_copy: 
　　　　source: /etc/herp/derp.conf 
　　　　dest: /root/herp-derp.conf.bak '''

4. 定义RETURN，该变量用来描述模块的返回数据信息

添加参数source和dest返回信息

module.exit_json(changed=True, source=module.params['source'], dest=module.params['dest'])

定义RETURN

RETURN = ''' source: description: source file used for the copy returned: success type: string sample: "/path/to/file.name" dest: description: destination of the copy returned: success type: string sample: "/path/to/destination.file" gid: description: group id of the file, after execution returned: success type: int sample: 100 group: description: group of the file, after execution returned: success type: string sample: "httpd" owner: description: owner of the file, after execution returned: success type: string sample: "httpd" uid: description: owner id of the file, after execution returned: success type: int sample: 100 mode: description: permissions of the target, after execution returned: success type: string sample: "0644" size: description: size of the target, after execution returned: success type: int sample: 1220 state: description: state of the target, after execution returned: success type: string sample: "file" '''

字符串的格式为yaml格式。

可以通过ansible-doc 来查看这些信息

ansible-doc -M library remote_copy

用于格式化字符串的一些选项，用于DOCUMENTATION

|函数| 描述 |例子|

|:---|:---|

|U() |格式化url |Required if I(state=present)|

|I() |格式化选项名称 |Mutually exclusive with I(project_src) and I(files)|

|M() |格式化模块名称 |See also M(win_copy) or M(win_template).|

|C() |格式化文件和选项值 |Or if not set the environment variable C(ACME_PASSWORD) will be used.|

Documentation 加载外部的文档

某些类别的模块有共同的文档信息，就可以使用docs_fragments共享出来。
所有的docs_fragments都可以在lib/ansible/utils/module_docs_fragments/ 目录下找到

在Documentation 字符串中添加下列字段，就可以添加外部的文档信息

extends_documentation_fragment:

  - files

   - validate