Ansible常用模块

可以从ansible-doc -l | grep module_name来找出想要的模块。再使用ansible-doc -s module_name来查看此模块的用法。

官方模块列表和说明: https://docs.ansible.com/ansible/latest/modules_by_category.html

关于模块的使用方法，需要注意的是state。很多模块都会有该选项，且其值几乎都包含有present和absent， 表示肯定和否定的意思。

ansible绝大多数模块都天然具有 幂等 特性，只有极少数模块如shell和command模块不具备幂等性。所谓的幂等性是指多次执行同一个操作不会影响最终结果。例如，ansible的yum模块安装rpm包时，如果待安装的包已经安装过了，则再次或多次执行安装操作都不会真正的执行下去。

再例如，copy模块拷贝文件时，如果目标主机上已经有了完全相同的文件，则多次执行copy模块不会真正的拷贝。ansible具有幂等性的模块在执行时，都会自动判断是否要执行。

shell和command

默认ansible使用的模块是command，即可以执行一些shell命令。shell和command的用法基本一样，实际上shell模块执行命令的方式是在远程使用/bin/sh来执行的，如/bin/sh ping。

command不能解析变量如$HOME和某些操作符"<", ">", "|", ";"以及"&"，所以明确要使用这些不可解析的操作符时，使用shell模块来代替command。

shell–Ansible官方使用说明文档

command–Ansible官方使用说明文档

ansible-doc -s shell
- name: Execute commands in nodes.
       action: shell
    chdir          # 在执行命令前，先cd到指定的目录下
    creates        # 用于判断命令是否要执行。如果指定的文件(可以使用通配符)存在，则不执行。
    removes        # 用于判断命令是否要执行。如果指定的文件(可以使用通配符)不存在，则不执行。
    executable     # 不再使用默认的/bin/sh解析并执行命令，而是使用此处指定的命令解析。
                   # 例如使用expect解析expect脚本。必须为绝对路径。

在ansible中使用shell或command模块一定要注意，它们默认不满足幂等性，很多操作会重复执行，但有些操作是不允许重复执行的。例如mysql的初始化命令mys ql_ins t all_db，它只能在第一次配置的过程中初始化一次，其他任何时候如非需要则不允许执行。这时候要实现幂等性，可以通过模块的creates和removes选项进行判断，但无论如何，在执行这两个模块的时候都需要考虑要执行的命令是否应该实现幂等性。

例子如下：

tasks:
  - shell: touch helloworld.txt creates=/tmp/hello.txt

但建议，在参数可能产生歧义的情况下，使用args来传递ansible的参数。如:

- shell: touch helloworld.txt
  args:
    creates: /tmp/hello.txt

# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
  shell: |
    set timeout 300
    spawn ssh admin@{{ cimc_host }}
    expect "password:"
    send "{{ cimc_password }}\n"
    expect "\n{{ cimc_name }}" send "connect host\n"
    expect "pxeboot.n12" send "\n"
    exit 0
  args:
    executable: /usr/bin/expect 
  delegate_to: localhost

复制模块copy

copy–Ansible官方使用说明文档

ansible-doc -l |grep copy

使用方法：

ansible-doc -s copy

ansible-doc -s copy
- name: Copy files to remote locations
  copy:
      backup=[yes|no]:   # 拷贝的同时也创建一个包含时间戳信息的备份文件，默认为no
      dest:              # 目标路径，只能是绝对路径，如果拷贝的文件是目录，则目标路径必须也是目录
      content:           # 直接以content给定的字符串或变量值作为文件内容保存到远程主机上，它会替代src选项
      directory_mode:    # 当对目录做递归拷贝时，设置了directory_mode将会使得只拷贝新建文件，
                         # 旧文件不会被拷贝。默认未设置
      follow=[yes|no]:   # 是否追踪到链接的源文件。
      force=[yes|no]:    # 设置为yes(默认)时，将覆盖远程同名文件。设置为no时，忽略同名文件的拷贝
      group:             # 设置远程文件的所属组
      owner:             # 设置远程文件的所有者
      mode:              # 设置远程文件的权限。使用数值表示时不能省略第一位，如0644。
                         # 也可以使用'u+rwx'或'u=rw,g=r,o=r'等方式设置。
      src:               # 拷贝本地源文件到远程，可使用绝对路径或相对路径。如果路径是目录，且目录后加了
                         # 斜杠"/"，则只会拷贝目录中的内容到远程，如果目录后不加斜杠，则拷贝目录本身和
                         # 目录内的内容到远程。

默认情况下，ansible copy会检查文件md5查看是否需要拷贝，相同则不会拷贝，否则会拷贝。如果设置force=yes，则当文件md5不同时(即文件内容不同)才覆盖拷贝，设置force=no时，则只拷贝对方没有的文件。

关于 copy 模块的backup这里使用几个例子说明下：

（1）当目标机上没有待copy的文件时，即使设置了backup=yes也是没有什么用处的，如：

ansible test -m copy -a "src=/tmp/temp/test.pub dest=/tmp backup=yes" -o -f 6

执行完之后，目标机 /tmp 目录下只有一个 copy 过去的 test.pub 文件，并没有像 test.pub.3286.2019-11-14@11:22:34~这样的备份文件出现～

（2）当目标机上已经有待copy的文件时，但server端与目标机上该文件是相同时（即server端该文件未更改），即使设置了backup=yes也是没有什么用处的。

（3）当目标机上已经有待copy的文件时，但server端与目标机上该文件是不同时（即server端该文件做了更改），设置了backup=yes，备份文件则会在目标机上目标文件路径下出现，如：

# 我们更改下server端 test.pub 文件的内容，然后执行ansible
ansible test -m copy -a "src=/tmp/temp/test.pub dest=/tmp backup=yes" -o -f 6

# 我们登入到目标机上 /tmp 目录下查看，会发现有一个备份文件出现，即 test.pub.3286.2019-11-14@11:22:34~ ，它的内容就是上次 server 端copy过来的文件内容～

如果拷贝的是目录，则目标路径必须是目录路径。如果使用”/”结尾，则拷贝的是目录中的文件，如果不以斜杠结尾，则拷贝的是目录加目录中的文件。举例如下：

（1）情况一：使用”/”结尾

## server端

# pwd
/tmp/temp
# ll
-rw-r--r-- 1 root root    0 11月 13 11:18 a.log
-rwxr-xr-x 1 root root  338 11月 13 11:31 auto_sshcopyid.exp
-rw------- 1 root root 1679 11月 13 10:31 id_rsa
-rw-r--r-- 1 root root  395 11月 13 10:31 id_rsa.pub
-rw-r--r-- 1 root root  416 11月 13 11:27 sshkey.sh
-rw------- 1 root root 1679 11月 13 10:34 test
-rw-r--r-- 1 root root  342 11月  5 10:48 test01.py
-rw-r--r-- 1 root root   75 11月  5 14:23 test02.py
-rw-r--r-- 1 root root  299 11月  5 16:18 test03.py
-rw-r--r-- 1 root root  371 11月  5 18:52 test04.py
-rw-r--r-- 1 root root  217 11月  5 22:26 test05.py
-rw-r--r-- 1 root root   60 11月  5 22:26 test06.py
-rw-r--r-- 1 root root  406 11月 14 11:22 test.pub

执行使用”/”结尾，则拷贝的是目录中的文件：

ansible test -m copy -a "src=/tmp/temp/ dest=/tmp/test" -o -f 6

查看目标机 /tmp/test 目录的内容：

# pwd
/tmp/test
# ll
总用量 48
-rw-r--r-- 1 root root    0 11月 14 11:39 a.log
-rw-r--r-- 1 root root  338 11月 14 11:39 auto_sshcopyid.exp
-rw-r--r-- 1 root root 1679 11月 14 11:39 id_rsa
-rw-r--r-- 1 root root  395 11月 14 11:39 id_rsa.pub
-rw-r--r-- 1 root root  416 11月 14 11:39 sshkey.sh
-rw-r--r-- 1 root root 1679 11月 14 11:39 test
-rw-r--r-- 1 root root  342 11月 14 11:39 test01.py
-rw-r--r-- 1 root root   75 11月 14 11:39 test02.py
-rw-r--r-- 1 root root  299 11月 14 11:39 test03.py
-rw-r--r-- 1 root root  371 11月 14 11:39 test04.py
-rw-r--r-- 1 root root  217 11月 14 11:39 test05.py
-rw-r--r-- 1 root root   60 11月 14 11:39 test06.py
-rw-r--r-- 1 root root  406 11月 14 11:39 test.pub

（2）情况二：不以斜杠结尾

执行不以斜杠”/”结尾，则拷贝的是目录加目录中的文件：

ansible test -m copy -a "src=/tmp/temp dest=/tmp/test01 backup=yes" -o -f 6

查看目标机 /tmp/test01 目录的内容：

# pwd
/tmp/test01
# ll
总用量 0
drwxr-xr-x 2 root root 224 11月 14 11:40 temp
# cd temp
# pwd
/tmp/test01/temp
# ll
总用量 48
-rw-r--r-- 1 root root    0 11月 14 11:40 a.log
-rw-r--r-- 1 root root  338 11月 14 11:40 auto_sshcopyid.exp
-rw-r--r-- 1 root root 1679 11月 14 11:40 id_rsa
-rw-r--r-- 1 root root  395 11月 14 11:40 id_rsa.pub
-rw-r--r-- 1 root root  416 11月 14 11:40 sshkey.sh
-rw-r--r-- 1 root root 1679 11月 14 11:40 test
-rw-r--r-- 1 root root  342 11月 14 11:40 test01.py
-rw-r--r-- 1 root root   75 11月 14 11:40 test02.py
-rw-r--r-- 1 root root  299 11月 14 11:40 test03.py
-rw-r--r-- 1 root root  371 11月 14 11:40 test04.py
-rw-r--r-- 1 root root  217 11月 14 11:40 test05.py
-rw-r--r-- 1 root root   60 11月 14 11:40 test06.py
-rw-r--r-- 1 root root  406 11月 14 11:40 test.pub

template模块

template模块用法和copy模块用法基本一致，它主要用于复制配置文件。template–Ansible官方使用说明文档

ansible-doc -s template
- name: Template a file out to a remote server
  template:
      backup:   # 拷贝的同时也创建一个包含时间戳信息的备份文件，默认为no
      dest:     # 目标路径
      force:    # 设置为yes (默认)时，将覆盖远程同名文件。设置为no时，忽略同名文件的拷贝
      group:    # 设置远程文件的所属组
      owner:    # 设置远程文件的所有者
      mode:     # 设置远程文件的权限。使用数值表示时不能省略第一位，如0644。
                # 也可以使用'u+rwx' or 'u=rw,g=r,o=r'等方式设置
      src:      # ansible控制器上Jinja2格式的模板所在位置，可以是相对或绝对路径
      validate: # 在复制到目标主机后但放到目标位置之前，执行此选项指定的命令。
                # 一般用于检查配置文件语法，语法正确则保存到目标位置。
                # 如果要引用目标文件名，则使用%s，下面的示例中的%s即表示目标机器上的/etc/nginx/nginx.conf。

示例如下：

ansible centos -m template -a "src=/tmp/nginx.conf.j2 dest=/etc/nginx/nginx.conf mode=0770 owner=root group=root backup=yes validate='nginx -t -c %s'" -o -f 6

虽然template模块可以按需求修改配置文件内容来复制模板到被控主机上，但是有一种情况它是不能解决的:不同被控节点所需的配置文件差异很大，并非修改几个变量就可以满足。例如在centos 6和centos 7上通过yum安装的 nginx，它们的配置文件内容相差非常大，且centos 6上的nginx的默认就有一个/etc/nginx/conf.d/default.conf。 如果直接复制同一个模板的nginx配置文件到centos 6和centos 7上，很可能导致某一版本的nginx不能启动。

这时就有必要在复制模板时挑选对应发行版的模板文件进行配对复制，例如要复制到 centos 6上的源模板是 nginx6.conf.j2，复制到centos 7上的源模板是nginx7.conf.j2。这种行为可以称之为”基于变量选择文件或模板”。

---
 - tasks:
     - name: template file based var
       template: src=/templates/nginx{{ ansible_distribution_major_version }}.conf.j2 dest=/etc/nginx/nginx.conf validate="/usr/sbin/nginx -t -c %s"

还可以在文件内容中指定jinja2的替代变量，在ansible执行时首先会根据变量内容进行渲染，渲染后再执行相关模块。例如，此处的template模块，复制一个基于发行版本号的yum源配置文件。以下是某个repo文件模板 base.repo.j2的内容。

[epel]
name=epel
baseurl=http://mirrors.aliyun.com/epel/{{ ansible_distribution_major_version }}Server/x86_64/ enable=1
gpgcheck=0

再复制即可。

---
 - tasks:
     - template: src=my.repo.j2 dest=/etc/yum.repos.d/my.repo

文件模块file

管理文件、目录的属性，也可以创建文件或目录。file–Ansible官方使用说明文档

ansible-doc -s file
- name: Manage files and file properties
  file:
      group:   # file/directory的所属组
      owner:   # file/directory的所有者
      mode:    # 修改权限，格式可以是0644、'u+rwx'或'u=rw,g=r,o=r'等
      path:    # 指定待操作的文件，可使用别名'dest'或'name'来替代path
      recurse: # (默认no)递归修改文件的属性信息，要求state=directory
      src:     # 要链接到的文件的路径。
               # 这只适用于state=link和state=hard。
               # 对于state=link，这也将接受一个不存在的路径。
               # 相对路径相对于正在创建的文件(路径)，这是Unix命令ln -s SRC DEST处理相对路径的方式。
      state:   # directory:如果目录不存在则递归创建
               # file:文件不存在时，不会被创建(默认值)
               # touch:touch由path指定的文件，即创建一个新文件，或修改其mtime和atime
               # link:修改或创建软链接
               # hard:修改或创建硬链接
               # absent:目录和其中的文件会被递归删除，文件或链接将取消链接状态

需要注意的是，file模块可以递归创建目录，但是不能在不存在的目录中创建文件，只能先创建目录，再在此目录中创建文件。我们做个测试验证下：

# 被控制机上并不存在/root/test这个目录
# 使用ansible在被控制机上/root/test目录下创建foo.conf
ansible test -m file -a "path=/root/test/foo.conf owner=duser group=duser mode='0644' state=touch"

ansible执行结果是：

192.168.246.187 | FAILED! => {
    "changed": false,    ## 失败
    "msg": "Error, could not touch target: [Errno 2] 没有那个文件或目录: b'/root/test/foo.conf'",
    "path": "/root/test/foo.conf"
}

# 现在我们在被控制机上创建/root/test目录
# 再次执行ansible
ansible test -m file -a "path=/root/test/foo.conf owner=duser group=duser mode='0644' state=touch"

ansible执行结果是：

192.168.246.187 | CHANGED => {
    "changed": true,  ## 成功
    "dest": "/root/test/foo.conf",
    "gid": 1009,
    "group": "duser",
    "mode": "0644",
    "owner": "duser",
    "size": 0,
    "state": "file",
    "uid": 1009
}

创建目录，并递归修改目录的属性。

ansible test -m file -a "path=/tmp/xyz/test state=directory owner=root group=root mode='0755' recurse=yes"

修改目录/tmp/xyz/test中test的权限

ansible test -m file -a "path=/tmp/xyz/test state=directory mode='0777'"

创建或修改文件属性／权限

ansible test -m file -a "path=/tmp/xyz/test/wtf.txt state=touch mode='0644'"

拉取文件模块fetch

和copy工作方式类似，只不过是从远程主机将文件拉取到本地端，存储时使用主机名作为目录树，且只能拉取文件不能拉取目录！

fetch–Ansible官方使用说明文档

ansible-doc -s fetch
- name: Fetch files from remote nodes
  fetch:
      dest:              # 本地存储拉取文件的目录。例如dest=/data，src=/etc/fstab,
                         # 远程主机名host.exp.com，则保存的路径为/data/host.exp.com/etc/fstab。
      fail_on_missing:   # 当设置为yes时，如果拉取的源文件不存在，则此任务失败。默认为no。
      flat:              # 改变拉取后的路径存储方式。如果设置为yes，且当dest以"/"结尾时，将直接把源文件
                         # 的basename存储在dest下。显然，应该考虑多个主机拉取时的文件覆盖情况。
      src:               # 远程主机上的源文件。只能是文件，不支持目录。在未来的版本中可能会支持目录递归拉取。
      validate_checksum: # fetch到文件后，检查其md5和源文件是否相同。

存储为/tmp/192.168.246.187/etc/fstab:

ansible test -m fetch -a "src=/etc/fstab dest=/tmp"

存储为/tmp/fstab:

ansible test -m fetch -a "src=/etc/fstab dest=/tmp/ flat=yes"

存储为/tmp/fstab-192.168.246.187:

ansible test -m fetch -a "src=/etc/fstab dest=/tmp/fstab-{{inventory_hostname}} flat=yes"

这里说明一点：

上面中的{{inventory_hostname}}指的是/etc/ansible/hosts中的主机别名，如：

# /etc/ansible/hosts如下定义：
[test]
192.168.246.187
[test:vars]
ansible_ssh_private_key_file=/root/.ssh/rsa_back/id_rsa
ansible_python_interpreter=/usr/local/python3/bin/python3

这种情况下控制端生成的文件名就是/tmp/fstab-192.168.246.187。

# /etc/ansible/hosts如下定义：
[test]
nginx ansible_ssh_host=192.168.246.187
[test:vars]
ansible_ssh_private_key_file=/root/.ssh/rsa_back/id_rsa
ansible_python_interpreter=/usr/local/python3/bin/python3

这种情况下控制端生成的文件名就是/tmp/fstab-nginx。

rsync模块synchronize

synchronize模块用于实现rsync的简单版常用功能，它无法实现完整版的rsync，毕竟rsync功能太多太细致。如果要使用rsync，还是应该使用command或shell模块来调用rsync命令。

完整的rsync功能见rsync命令中文手册。

ansible-doc -s synchronize
- name: A wrapper around rsync to make common tasks in your playbooks quick and easy
  synchronize:
      src:           # 指定待传输的源文件。可以是相对路径，也可以是绝对路径。
      dest:          # 目标路径。可以是绝对路径，也可以是相对路径。
      mode:          # 指定推(push)还是拉(pull)的传输模式。
                     # push时，本地为sender端，pull时，远程为sender端。默认为push。
      archive:       # 等价于rsync的"-a"选项，即使用归档模式。它等价于rsync的"-rtopgDl"选项。值为yes/no。
      times:         # 保留mtime属性,值为yes/no。
      group:         # 保留所属组属性,值为yes/no。
      owner:         # 保留所有者属性,值为yes/no。
      links:         # 拷贝链接文件自身,值为yes/no。
      perms:         # 保留权限属性,值为yes/no。
      recursive:     # 递归到目录中的文件,值为yes/no。
      compress:      # 传输过程中压缩传输。应该总是开启，除非遇到问题。即rsync的"-z"选项。值为yes/no，默认是yes。
      copy_links：   # 拷贝软链接的文件名和其指向的文件的内容。即a指向b文件时，将在目标端生成a普通
                     # 文件，但此文件中的内容是b中的内容。
      dirs：         # 非递归方式传输目录。
      delete：       # 目标端如果比源端文件多，则删除这些多出来的文件，要求recursive=yes。
      checksum：     # 等价于"-c"选项，将基于文件的checksum来判断是否同步，而不是默认的quick check
                     # 算法，该算法基于文件大小和最近的mtime来判断是否要同步。该选项会大幅降低效率，
                     # 应谨慎使用。注意，它无法影响archive，即archive仍会启用。
      existing_only：# receiver端没有的文件不同步。但仍会传输，只是临时文件重组后不重命名而已。
      partial：      # 等价于"--partial"选项。默认rsync在传输中断时会删除传输了一半的文件，指定该选
                     # 项将保留这部分不完整的文件，使得下次传输时可以直接从未完成的数据块开始传输。
      dest_port：    # ssh的连接端口。
      rsync_opts：   # 指定额外的rsync选项。使用数组的方式传递这些选项。
      rsync_path：   # 等价于"--rsync-path"选项，目的是启动远程rsync。
                     # 例如可以指定[--rsync-path=rsync]，甚至[--rsync-path=cd /tmp/c && rsync]。
                     # 当不指定rsync路径时，默认为/usr/bin/rysnc。
      rsync_timeout：# 指定rsync在多久时间内还没有数据传输就超时退出。
      verify_host：  # 对目标主机进行ssh的host key验证。

说明

本博文是参考马龙帅大佬文章整理生成，属于博主读书笔记，如有侵权，请大佬与我联系，立删！

最后，感谢开源，拥抱开源～