开发插件规则
- 用Python编写用Python编写
- 引发错误,就是遇到问题后,主动抛出异常
- 返回以unicode编码的字符串,主要是兼容 Jinja2
- 符合Ansible的配置和文档标准,就是可以通过 `ansible.cfg` 进行配置
使用兼容的 Python 版本编写
由于开发出来的插件将在控制器上执行,因此您必须使用兼容版本的Python(Python 2(2.7版)或 Python 3(3.5版及更高版本)的)进行编写。
抛出异常错误信息
应该通过引发`AnsibleError()`或类似的类并返回描述错误的消息来返回插件执行过程中遇到的错误。
将其他异常包装到错误消息中时,应始终使用Ansible 的函数`to_native`来确保跨Python版本的字符串兼容性:
from ansible.errors import AnsibleError
from ansible.module_utils._text import to_native
try:
cause_an_exception()
except Exception as e:
raise AnsibleError('Something happened, this was original exception: %s' % to_native(e))
妥当处理字符串
您必须将插件返回的所有字符串转换为Python的unicode类型。转换为unicode可确保这些字符串可以通过Jinja2运行。
转换字符串:
from ansible.module_utils._text import to_text
result_string = to_text(result_string)
插件配置和文档标准
Ansible的在线帮助文档是根据每个模块的源代码中的`DOCUMENTATION`模块生成的。该`DOCUMENTATION`块必须是有效的YAML。
需要为您的插件定义可配置选项,在python文件的部分 `DOCUMENTATION` 中对其进行描述。
自Ansible 2.4版以来,回调和连接插件已经开始以这种方式声明配置要求了。现在大多数插件类型都执行相同的操作。这种方法可确保插件选项的文档始终是正确的和最新的。
`DOCUMENTATION`块中的所有字段均为小写。除非另有说明,否则所有字段都是必填字段:
DOCUMENTATION = '''
callback: log_plays
type: notification
short_description: write playbook output to log file
version_added: historical
description:
- 此插件的详细描述信息。
- 使用多条目,不要使用一个较长的语句。
- 不应该提及模块名称。
requirements:
- 必须要求清单
- 包括最低版本的限制
options:
log_folder:
version_added: '2.9' 此插件添加到 Ansible 时候的当时 Ansible 的版本。
default: 选项的默认值,如果 required 是 False, 则 default 可以设置
description: 此选项的作用的详细说明。应该用完整的句子写成。
env:
- name: 环境变量的名字
ini:
- section: 在 asible.cfg 中的配置块名称
key: log_folder在对应配置块下面的变量名称
required: True/False 必需时为 True,如果不设置,就认为
不是必须的。
type: int/str/list 不是必须的
- 要访问插件中的配置设置,请使用`self.get_option("log_folder")`。
- 如果需要显式个配置选项设置值,请使用`self.set_options()`