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时显示执行时长: