Ansible教程：模块介绍-马育民老师

# 介绍
Ansible 模块（Module）是 Ansible 的 **最小执行单元**，也叫插件。执行 `ansible`/`ansible-playbook` 时，模块会被临时传输到目标主机执行，执行完成后自动删除，无常驻代理。

**特点：****无Agent**；绝大多数模块是幂等的（多次执行结果一致，不会重复改动）。

# 一、模块分类
1. **核心模块（core modules）**：官方维护，常用基础模块，优先内置。
2. **集合模块（collection modules）**：Ansible 2.10+ 把大量模块剥离到 `ansible.collections`，需要安装对应集合。
3. **自定义模块**：自己用 Python/Shell 编写。

# 二、高频常用模块详解
### 1. command
执行简单命令，**不支持管道、重定向、变量替换**（底层不是shell）
```yaml
- name: 查看主机时间
  command: date
```
> 注意：不要用 `| > &`，有shell需求改用 `shell`

### 2. shell
在目标主机shell中执行命令，支持管道、重定向
```yaml
- name: 过滤进程
  shell: ps aux | grep nginx
```
> 安全提醒：尽量优先command；传入用户变量时注意注入风险。

### 3. raw
直接发送原始命令，**不依赖目标主机有Python**。
适用场景：新裸机、网络设备、没有Python的系统。
```yaml
- name: 无Python机器执行命令
  raw: hostname
```

### 4. file
文件/目录管理，创建、删除、修改权限属主
```yaml
# 创建目录
- file:
    path: /data/test
    state: directory  # directory=目录，touch=文件，absent=删除
    owner: root
    group: root
    mode: '0755'
```

### 5. copy
把**控制端本地文件**拷贝到远程主机
```yaml
- name: 推送配置文件
  copy:
    src: ./nginx.conf
    dest: /etc/nginx/nginx.conf
    owner: root
    mode: '0644'
    backup: yes # 改动前备份原文件
```

### 6. fetch
和copy反向：**拉取远程文件到控制端**，只能拉文件，不能拉目录
```yaml
- name: 收集远程日志
  fetch:
    src: /var/log/messages
    dest: ./log_backup/
```
> 保存路径：`dest/主机名/src路径`

### 7. template
模板文件（Jinja2）推送远程，支持变量渲染
```yaml
- name: 渲染模板
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
```
> 模板文件内可写 `{{ nginx_port }}` 变量

### 8. yum / dnf
RHEL/CentOS 系列软件包管理
```yaml
- name: 安装nginx
  yum:
    name: nginx
    state: present # present安装，latest最新版，absent卸载
```
> CentOS8+推荐用 `dnf`

### 9. apt
Debian/Ubuntu 包管理
```yaml
- name: 安装nginx
  apt:
    name: nginx
    state: present
    update_cache: yes # 相当于apt update
```

### 10. service / systemd
服务启停、开机自启
```yaml
- name: 启动nginx并开机自启
  service:
    name: nginx
    state: started # started/stopped/restarted/reloaded
    enabled: yes
```
> systemd模块支持更多systemd特性（daemon_reload等）

### 11. user
用户管理，创建删除用户、设置uid、密码
```yaml
- name: 创建test用户
  user:
    name: test
    uid: 1008
    shell: /bin/bash
    state: present
```

### 12. group
用户组管理
```yaml
- group:
    name: ops
    gid: 2000
    state: present
```

### 13. lineinfile
修改文件**单行内容**，适合替换/新增一行
```yaml
- name: 修改sshd配置允许密码登录
  lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PasswordAuthentication'
    line: 'PasswordAuthentication yes'
```

### 14. blockinfile
在文件中插入**一段多行文本**，会自动加标记 `# BEGIN/END ANSIBLE MANAGED BLOCK`
```yaml
- blockinfile:
    path: /etc/profile
    block: |
      export JAVA_HOME=/usr/local/jdk
```

### 15. unarchive
解压压缩包到远程主机
- `remote_src=no`：压缩包在**控制机**（默认），上传后解压
- `remote_src=yes`：压缩包已经在**远程主机**，直接解压
```yaml
- name: 解压本地jdk包到远程
  unarchive:
    src: jdk.tar.gz
    dest: /usr/local/
    remote_src: no
```

### 16. get_url
远程主机下载网络文件（wget/curl）
```yaml
- name: 下载nginx源码包
  get_url:
    url: https://xxx/nginx.tar.gz
    dest: /tmp/nginx.tar.gz
```

### 17. cron
定时任务管理
```yaml
- name: 每天凌晨2点备份
  cron:
    name: backup
    minute: 0
    hour: 2
    job: /bin/sh /data/backup.sh
```

### 18. mount
挂载文件系统，写入/etc/fstab持久化
```yaml
- name: 挂载/data分区
  mount:
    path: /data
    src: /dev/sdb1
    fstype: ext4
    state: mounted # mounted临时挂载+fstab写入；present只写fstab
```

### 19. assert
断言校验，用于playbook做条件检查，失败直接终止playbook
```yaml
- assert:
    that:
      - ansible_distribution == "CentOS"
    fail_msg: "仅支持CentOS系统"
```

# 三、模块使用方式
### 1. Ad-hoc 命令行直接调用模块
格式：`ansible 主机组 -m 模块名 -a "模块参数"`
```bash
ansible web -m shell -a "df -h"
ansible web -m file -a "path=/tmp/abc state=touch"
```

### 2. Playbook YAML中调用
```yaml
tasks:
  - name: task描述
    模块名:
      参数1: 值
      参数2: 值
```

# 四、查看模块文档
```bash
# 查看模块帮助
ansible-doc file
# 只看示例
ansible-doc -s copy
```

# 五、模块选择建议（避坑）
1. 优先使用**原生模块**，不要无脑shell/command：原生模块自带幂等、错误处理；shell每次都会返回changed。
2. 单行修改文件用 `lineinfile`，多行用 `blockinfile`，批量模板渲染用 `template`。
3. 需要Jinja变量渲染文件 → template；单纯静态文件拷贝 → copy。

原文出处：/show_1GW45HDJMSJG.html