Ansible之路——第八章： Ansible 模块

 

 

ansible本身是没有部署能力的，它只是个框架，它的模块才有真正的部署能力。

8.1 模块定义与使用方式

模块(也被称为 “task plugins” 或 “library plugins”)是在 Ansible 中实际在执行的。它们就是在每个 playbook 任务中被执行的。你也可以仅仅通过 ‘ansible’ 命令来运行它们。

每个模块都能接收参数，几乎所有的模块都接受键值对(key=value)参数，空格分隔。一些模块不接收参数，只需在命令行输入相关的命令就能调用。

在 playbook 中, Ansible 模块以类似的方式执行：

 

也可以简写成:

 

另一种给模块传递参数的方式是使用 yaml 语法，这也被称为‘complex args’：

 

无论你是使用命令行还是 playbooks 所有模块都会返回以JSON格式组织的数据。

模块努力使自身幂等,这意味着它们会尽可能避免对系统做出改动除非那是必须的。当使用 Ansible playbooks 时,这些模块能够触发‘change events’,以这种形式通知‘handlers’去运行附加任务。

每个模块的文档能够通过命令行的 ansible-doc 工具来获取:

ansible-doc yum

列出所有已安装的模块文档:

ansible-doc -l

 

8.2 模块分类

ansible的模块主要分为核心模块、额外模块和自定义模块。

核心模块是ansible 团队维护的核心模块，同样也是 ansible 自带的模块，在收到的请求中，它们有比 “extras” 源更高的优先级。

核心模块的源码托管在 Github ： https://github.com/ansible/ansible-modules-core

 

额外模块是当前ansible附带的,但是也可能在以后被分开.额外模块主要被社区人员维护.非核心模块仍然是完全可用的,但是在发出和拉取请求时可能收到稍微低的响应速率。

受欢迎的的 “extras” 模块将来可能会提升为核心模块。

这些额外的模块托管在Github上：https://github.com/ansible/ansible-modules-extras

 

自定义模块：如果核心模块或者额外模块都无法满足需求，那么可以自己编写ansible模块。

 

8.3 自定义模块编写

先导出环境变量，我们自定义模块的目录

export ANSIBLE_LIBRARY=/usr/share/my_modules/

把自己写的模块放到这个目录中，ansible在执行的时候会读取ANSIBLE_LIBRARY这个环境变量来查找对应的模块文件。

如果没有设置环境变量，则可以在ansible的配置文件中添加：

[defaults]
library        = /usr/share/my_modules/

 

下面开始编写我们自定义的模块：mymodule

8.3.1 简单版

 

8.3.2 带参数版

 

参数的其他设定方法

参数类型	方法
必填项	arg=dict(required=True)
默认项	arg=dict(default='yes')
选择项	arg=dict(defalut='yes',choices['yes','no'])
布尔值	arg=dict(type='bool')
字符型	arg=dict(type='str')
任选变量	arg1=dict(aliaes=['arg2','arg3'])

 

任选变量的说明，即以下的命令是一样的效果：

ansible xxx -m mymodule -a 'arg1='xxx'
ansible xxx -m mymodule -a 'arg2='xxx'
ansible xxx -m mymodule -a 'arg3='xxx'

 

参数设定的模板：可以根据模板任意的更改为我们所需的。

 

8.3.3 模块状态返回的标识

1、"chang":"false"并不代表什么，它只是一个记录的值

2、需修改为"chang":"True"，只需result = dict(echo=arg,changed=True)

3、可添加其他的返回的标识，只需：

result = dict(echo=arg,changed=True,good='good')

 

8.3.4 自定义模块的文档编写

我们在查看某个模块的帮助文档时，一般都是通过ansible-doc来查看该模块的使用说明，如：

 

模块的文档一般是定义在模块内部的，因此可以在我们的自定义模块前面加上一部分文档信息。

如：

 

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

• ANSIBLE_METADATA
• DOCUMENTATION
• EXAMPLES
• RETURNS
• Python imports

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

 

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

 

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

 

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

 

注：字符串的格式为yaml格式。

 

另外，Documentation 也可以加载外部的文档。

某些类别的模块有共同的文档信息，就可以使用docs_fragments共享出来。所有的docs_fragments都可以在ansible/utils/module_docs_fragments/ 目录下找到。这样在通过ansible-doc查看帮助信息的时候，可以将共享文档里面的内容一起加载。

 

被加载的文档必须是存在的，否则会报字符串格式化错误：

ERROR! module mymodule has a documentation error formatting or is missing documentation.

 

8.4 常用模块

8.4.1 setup

主要用于获取主机信息。在playbooks里经常会用到的一个参数gather_facts就与该模块相关。setup模块下经常使用的一个参数是filter参数，具体使用示例如下：

# ansible localhost -m setup -a 'filter=ansible_*_mb'  //查看主机内存信息
# ansible localhost -m setup -a 'filter=ansible_eth[0-2]'   //查看接口为eth0-2的网卡信息
# ansible all -m setup --tree /tmp/facts   //将所有主机的信息输入到/tmp/facts目录下，每台主机的信息输入到主机名文件中（/etc/ansible/hosts里的主机名）

注：playbook中如果不需要获取主机信息，建议设置gather_facts为no或者使用ansible的缓存来保存各主机的信息。

8.4.2 ping

测试主机是否是通的，用法很简单，涉及参数为data（默认为pong），如果data为crash，则抛出异常。

 

8.4.3 file

file模块主要用于远程主机上的文件操作，file模块包含如下选项：

n  force：需要在两种情况下强制创建软链接，一种是源文件不存在但之后会建立的情况下；另一种是目标软链接已存在,需要先取消之前的软链，然后创建新的软链，有两个选项：yes|no

n  group：定义文件/目录的属组 

n  mode：定义文件/目录的权限

n  owner：定义文件/目录的属主

n  path：必选项，定义文件/目录的路径

n  recurse：递归的设置文件的属性，只对目录有效

n  src：要被链接的源文件的路径，只应用于state=link的情况

n  dest：被链接到的路径，只应用于state=link的情况 

n  state：

²  directory：如果目录不存在，创建目录

²  file：即使文件不存在，也不会被创建

²  link：创建软链接

²  hard：创建硬链接

²  touch：如果文件不存在，则会创建一个新的文件，如果文件或目录已存在，则更新其最后修改时间

²  absent：删除目录、文件或者取消链接文件

 

8.4.4 copy 

复制文件到远程主机，copy模块包含如下选项：

n  backup：在覆盖之前将原文件备份，备份文件包含时间信息。有两个选项：yes|no 

n  content：用于替代"src",可以直接设定指定文件的值 

n  dest：必选项。要将源文件复制到的远程主机的绝对路径，如果源文件是一个目录，那么该路径也必须是个目录 

n  directory_mode：递归的设定目录的权限，默认为系统默认权限

n  force：如果目标主机包含该文件，但内容不同，如果设置为yes，则强制覆盖，如果为no，则只有当目标主机的目标位置不存在该文件时，才复制。默认为yes

n  others：所有的file模块里的选项都可以在这里使用

n  src：要复制到远程主机的文件在本地的地址，可以是绝对路径，也可以是相对路径。如果路径是一个目录，它将递归复制。在这种情况下，如果路径使用"/"来结尾，则只复制目录里的内容，如果没有使用"/"来结尾，则包含目录在内的整个内容全部复制，类似于rsync。

n  remote_src：表示源文件src是否在远程主机上。

 

8.4.5 service

用于管理服务，该模块包含如下选项：

n  arguments：给命令行提供一些选项

n  enabled：是否开机启动 yes|no

n  name：必选项，服务名称

n  pattern：定义一个模式，如果通过status指令来查看服务的状态时，没有响应，就会通过ps指令在进程中根据该模式进行查找，如果匹配到，则认为该服务依然在运行

n  runlevel：运行级别

n  sleep：如果执行了restarted，在则stop和start之间沉睡几秒钟

n  state：对当前服务执行启动，停止、重启、重新加载等操作（started,stopped,restarted,reloaded）

例如：

 

8.4.6 cron

用于管理计划任务，包含如下选项：

n  backup：对远程主机上的原任务计划内容修改之前做备份

n  cron_file：如果指定该选项，则用该文件替换远程主机上的cron.d目录下的用户的任务计划

n  day：日（1-31，*，*/2,……）

n  hour：小时（0-23，*，*/2，……） 

n  minute：分钟（0-59，*，*/2，……）

n  month：月（1-12，*，*/2，……）

n  weekday：周（0-7，*，……）

n  job：要执行的任务，依赖于state=present

n  name：该任务的描述

n  special_time：指定什么时候执行，参数：reboot,yearly,annually,monthly,weekly,daily,hourly

n  state：确认该任务计划是创建还是删除

n  user：以哪个用户的身份执行

 

8.4.7 yum

使用yum包管理器来管理软件包，其选项有：

n  config_file：yum的配置文件

n  disable_gpg_check：关闭gpg_check

n  disablerepo：不启用某个源

n  enablerepo：启用某个源

n  name：要进行操作的软件包的名字，也可以传递一个url或者一个本地的rpm包的路径

n  state：状态（present，absent，latest）

 

8.4.8 get_url

该模块主要用于从http、ftp、https服务器上下载文件（类似于wget），主要有如下选项：

n  sha256sum：下载完成后进行sha256 check；

n  timeout：下载超时时间，默认10s

n  url：下载的URL

n  url_password、url_username：主要用于需要用户名密码进行验证的情况

n  use_proxy：是使用代理，代理需事先在环境变更中定义 

 

8.4.9 template 

使用了Jinjia2格式作为文件模版，进行文档内变量的替换的模块。常用选项有：

n  backup：建立个包括timestamp在内的文件备份，以备不时之需。选项：yes/no（默认）

n  dest：远程节点上的绝对路径，用于放置template文件。必选参数

n  group：设置远程节点上的的template文件的所属用户组

n  mode：设置远程节点上的template文件权限。类似Linux中chmod的用法

n  owner：设置远程节点上的template文件所属用户

n  src：本地Jinjia2模版的template文件位置。必选参数

 

8.4.10 fail

此模块使用自定义消息使进度失败。选项：

n  msg：用于执行失败的自定义消息。默认为"Failed as requested from task

 

当使用when满足某种条件时，它可以用于挽救。

 

8.5 第三方模块

8.5.1 时间计时模块

Ansible中可以加入一个计时模块在执行ansible-playbook时显示执行时长。方便使用。

配置方法：

 

 ansible2.0以上版本需在ansible.cfg中加入以下内容：

[defaults] 下面加入
callback_whitelist= profile_tasks

 

再次执行ansbile-playbook时显示执行时长：