Ansible常用模块分类
一、系统管理类
1. 计划任务与定时
-
crond（Linux 定时任务管理）
- 时间规则：
minute（分钟）、hour（小时）、day（日期）、month（月份）、week（星期） - 任务定义：
job（要执行的命令/脚本，如"/usr/bin/backup.sh"） - 状态控制：
state（present新增任务、absent删除任务 ） - 场景：周期性日志切割、数据库备份
- 时间规则：
-
at（一次性定时任务）
- 时间参数：
at_time（指定执行时间，如"now + 1 hour"、"17:00 tomorrow"） - 任务内容：
command（要执行的命令，如"shutdown -r now"） - 状态控制：
state（present新增任务、absent删除任务 ） - 场景：系统维护前延迟重启
- 时间参数：
2. 用户与组管理
-
user（用户生命周期管理）
- 基础属性：
name（用户名）、uid（用户 ID）、shell（默认 Shell，如/bin/bash）、create_home（是否创建家目录，yes/no） - 权限与密码：
password（加密后的密码，需用ansible-vault或mkpasswd生成 ）、groups（附加用户组，如["wheel", "docker"]） - 状态控制：
state（present创建用户、absent删除用户 ） - 高级：
expires（账户过期时间，Unix 时间戳 ）、remove（删除用户时是否连带删除家目录，yes/no）
- 基础属性：
-
group（用户组管理）
- 基础属性：
name（组名）、gid（组 ID） - 状态控制：
state（present创建组、absent删除组 ） - 扩展：
system（是否为系统组，yes/no，影响组 ID 范围 ）
- 基础属性：
3. 系统配置与初始化
-
sysctl（内核参数调整）
- 参数设置：
name（参数名，如net.ipv4.ip_forward）、value（参数值，如1开启 IP 转发 ） - 持久化：
state（present确保参数生效并写入/etc/sysctl.conf） - 场景：调整网络转发、文件描述符限制
- 参数设置：
-
lineinfile（精准修改配置文件行）
- 目标文件：
path（要修改的文件路径，如/etc/nginx/nginx.conf） - 内容控制：
line（要写入的行，如"worker_processes auto;"）、regexp（匹配行的正则，用于替换或确保唯一 ） - 状态：
state（present确保行存在、absent删除行 ） - 高级：
backrefs（正则匹配时保留原内容 ）、insertafter/insertbefore（指定插入位置，如EOF前 ）
- 目标文件：
4. 软件包管理
-
yum（RHEL/CentOS 系列）
- 包操作：
name（包名，支持列表/通配符，如["nginx", "python*"]） - 状态：
state（present安装、latest升级到最新、absent卸载 ） - 缓存：
update_cache（yes/no，是否更新 yum 缓存 ） - 扩展：
disable_gpg_check（跳过 GPG 校验，yes/no，非安全场景临时用 ）
- 包操作：
-
apt（Debian/Ubuntu 系列）
- 包操作：
name（包名，如apache2、mysql-server） - 状态：
state（present安装、latest升级、absent卸载 ） - 缓存：
update_cache（yes/no，更新 apt 缓存 ） - 扩展：
force（强制安装/覆盖依赖，yes/no）
- 包操作：
-
homebrew（macOS）
- 包操作：
name（brew 包名，如git、vim） - 状态：
state（present安装、latest升级、absent卸载 ） - 扩展：
install_options（安装选项，如--with-python编译时启用 Python 支持 ）
- 包操作：
二、文件操作类
1. 基础文件管理
-
file（文件/目录属性、存在性控制）
- 路径：
path（目标路径，如/opt/app/config） - 类型与状态：
state（directory确保目录存在、file确保文件存在、link建软链接、absent删除 ） - 权限：
mode（权限，如0644、0755）、owner（属主）、group（属组） - 高级：
attributes（文件系统属性，如+i设为只读 ）
- 路径：
-
copy（本地→远程拷贝文件）
- 源与目标：
src（控制节点的源文件/目录）、dest（目标主机路径，如/tmp/upload/） - 内容替代：
content（直接写入文本内容，替代src，适合小配置 ） - 权限：
mode、owner、group（同file模块 ） - 特殊：
remote_src（yes时，src为目标主机本地路径，实现远程拷贝 ）
- 源与目标：
-
fetch（远程→本地拉取文件）
- 源与目标：
src（目标主机文件路径，如/var/log/syslog）、dest（控制节点存储目录，自动按主机名分级 ） - 扁平化：
flat（yes时，直接存为dest文件名，不分级 ） - 过滤：
fail_on_missing（文件不存在时是否失败，yes/no）
- 源与目标：
2. 模板与变量渲染
- template（带 Jinja2 渲染的文件拷贝）
- 源与目标：
src（模板文件，含{{ 变量 }}，如config.j2）、dest（目标路径，如/etc/nginx/nginx.conf） - 变量传递：结合 Ansible 变量（Playbook vars、Inventory 变量等 ）
- 权限：
mode、owner、group（同file模块 ） - 高级：
trim_blocks（去除 Jinja2 块的空行，yes/no）、lstrip_blocks（左 trim 空格，yes/no）
- 源与目标：
3. 归档与解压
-
archive（打包文件/目录）
- 源：
path（要打包的文件/目录，支持通配符，如/var/log/*.log） - 目标：
dest（打包后的归档路径，如/tmp/logs.tar.gz） - 格式：
format（tar、gz、zip等 ） - 过滤：
exclude_path（排除的路径，如"/var/log/old"）
- 源：
-
unarchive（解压归档）
- 源与目标：
src（归档文件路径，支持控制节点或远程主机路径 ）、dest（解压目标目录，如/opt/app） - 来源：
remote_src（yes时，src是目标主机路径；no时，src是控制节点路径 ） - 权限：
mode、owner、group（解压后文件权限 ） - 特殊：
extra_opts（解压额外参数，如tar --strip-components=1去掉一级目录 ）
- 源与目标：
三、网络管理类
1. 网络配置（Linux 网络）
-
nmcli（NetworkManager 管理）
- 连接管理：
conn_name（连接名，如"eth0-static"） - 类型：
type（ethernet、bridge等 ） - IP 配置：
ip4（IP 地址，如192.168.1.10/24）、gw4（默认网关，如192.168.1.1） - DNS：
dns4（DNS 服务器，如8.8.8.8） - 状态：
state（present确保存在、absent删除、up/down启停 ） - 高级：
master（桥接/ bonding 主设备，如"br0"）
- 连接管理：
-
network（传统网络脚本方式，兼容老系统）
- 网卡：
name（网卡名，如eth0） - IP 配置：
ip（IP 地址）、netmask（子网掩码）、gateway（网关 ） - 状态：
state（up/down启停网卡 ） - 持久化：
bootproto（dhcp/static，控制/etc/sysconfig/network-scripts配置 ）
- 网卡：
2. 网络设备配置（网络设备自动化）
-
ios_config（Cisco IOS 设备）
- 配置来源：
src（本地配置文件，如ios_config.txt）、lines（逐行命令，如"interface GigabitEthernet0/1"） - 设备连接：
provider（指定连接参数，如host、username、password） - 操作：
before（执行配置前的命令，如"configure terminal"）、after（执行配置后的命令，如"write memory"） - 替换模式：
replace（line按行替换、block按块替换 ） - 回滚：
backup（yes时备份原有配置，用于回滚 ）
- 配置来源：
-
nxos_config（Cisco Nexus 设备）
- 类似
ios_config，适配 Nexus OS 特性（如 ACI 配置、Nexus 特有命令 ） - 连接：
provider或使用 Ansible 网络连接插件
- 类似
3. 网络服务与检测
-
uri（HTTP/HTTPS 服务检测与交互）
- 目标：
url（请求地址，如https://example.com/api） - 方法：
method（GET、POST、PUT、DELETE等 ） - 参数：
body（POST/PUT数据，JSON 或表单，如'{"key": "value"}'）、headers（请求头，如Content-Type: application/json） - 验证：
status_code（期望返回状态码，如200）、validate_certs（是否校验 SSL 证书，yes/no） - 结果：
return_content（yes时返回响应内容 ）
- 目标：
-
ping（基础网络连通性检测）
- 极简：无特殊参数，返回
pong表示目标主机可连通 - 扩展：结合
ignore_errors处理非强制检测场景（如监控任务不中断 Playbook ）
- 极简：无特殊参数，返回
四、应用部署与容器类
1. 容器管理（Docker）
-
docker_image（镜像管理）
- 镜像：
name（镜像名，如nginx:latest） - 状态：
state（present确保存在、absent删除、build从 Dockerfile 构建 ） - 构建：
path（Dockerfile 路径，state=build时用 ）、dockerfile（指定 Dockerfile 名，如Dockerfile.prod） - 推送：
push（yes时推送到镜像仓库 ）、repository（推送的仓库地址，如docker.io/username/repo）
- 镜像：
-
docker_container（容器管理）
- 容器：
name（容器名，如webserver）、image（镜像名，如nginx:alpine） - 网络与端口：
ports（端口映射，如80:8080）、networks（网络模式，如bridge） - 存储：
volumes（数据卷挂载，如/host/path:/container/path） - 环境：
env（环境变量，字典形式，如{"DB_HOST": "db"}） - 状态：
state（started启动、stopped停止、absent删除、restarted重启 ）
- 容器：
2. 代码与应用部署
-
git（代码仓库拉取）
- 仓库：
repo（仓库地址，如https://github.com/user/repo.git） - 目标：
dest（本地路径，如/opt/app） - 版本：
version（分支、标签或提交 ID，如main、v1.0） - 强制：
force（yes时强制拉取覆盖本地修改 ） - 深度：
depth（克隆深度，如1只拉取最新提交，加速大仓库 ）
- 仓库：
-
pip（Python 包管理）
- 包：
name（包名，如requests、django） - 状态：
state（present安装、latest升级、absent卸载 ） - 版本：
version（指定版本，如django==4.0） - 环境：
virtualenv（虚拟环境路径，如/opt/venv） - 索引：
extra_args（指定 PyPI 源，如-i https://pypi.tuna.tsinghua.edu.cn/simple）
- 包：
3. 中间件与服务管理
-
service（系统服务启停，兼容 Systemd/Upstart 等）
- 服务：
name（服务名，如httpd、nginx） - 状态：
state（started启动、stopped停止、restarted重启、reloaded重载 ） - 开机启动：
enabled（yes/no，是否开机自启 ） - 扩展：
args（启动参数，如--debug）
- 服务：
-
systemd（Systemd 专属管理，功能更细）
- 服务：
name（服务单元名，如nginx.service） - 状态：
state（started、stopped等，同service） - 开机启动：
enabled（yes/no）、masked（yes时屏蔽服务，无法启动 ） - 重载：
daemon_reload（yes时重载 Systemd 单元文件 ）
- 服务：
五、监控与日志类
1. 日志与事件
-
syslog（写入系统日志）
- 日志内容：
msg（日志信息，如"Ansible 配置完成：nginx 启动"） - 日志级别：
priority（日志优先级，如info、warning、error） - 日志设备：
facility（日志设备，如user、daemon、local0） - 目标主机：
host（远程 syslog 服务器地址，默认写入本地 ）
- 日志内容：
-
logrotate（日志轮转配置）
- 目标文件：
path（要轮转的日志路径，如/var/log/nginx/access.log） - 轮转规则：
rotate（保留份数，如7）、daily/weekly/monthly（轮转频率 ） - 压缩：
compress（yes/no，是否压缩旧日志 ）、delaycompress（延迟压缩，保留最新 1 份未压缩 ） - 触发条件：
size（达到指定大小轮转，如100M） - 后置操作：
postrotate（轮转后执行的命令，如 `"systemctl reload nginx
- 目标文件：
2. 系统指标与信息采集
-
setup（采集目标主机 Facts 信息）
- 采集范围：默认无参数时，采集全量系统信息（CPU型号/核心数、内存总量/使用率、磁盘分区、网卡IP、操作系统版本等）
- 过滤采集：
filter（按规则筛选 Facts，支持通配符，如ansible_mem*仅采集内存相关、ansible_eth0仅采集 eth0 网卡信息、ansible_distribution*采集系统发行版相关） - 自定义 Facts：
fact_path（指定自定义 Facts 文件路径，如/etc/ansible/facts.d，支持.ini/.json/可执行脚本格式，脚本输出需符合 JSON 结构） - 应用场景：基于 Facts 动态适配配置（如根据
ansible_memtotal_mb设置 JVM 堆内存、根据ansible_os_family选择 yum/apt 模块）
-
stat（获取文件/目录详细属性）
- 目标路径：
path（文件/目录路径，如/etc/passwd、/var/log/nginx） - 采集信息：返回
size（大小，单位字节）、mode（权限，如0o644）、uid/gid（属主/属组ID）、mtime（最后修改时间）、ctime（最后状态变更时间）、checksum（文件校验和，默认 sha1）、exists（是否存在，布尔值） - 结果处理：
register（将采集结果存入变量，用于后续条件判断，如if stat_result.stat.exists == true则执行某任务） - 扩展参数：
follow（yes/no，是否跟随软链接，默认no）、get_checksum（yes/no，是否计算文件校验和，默认yes）、get_mime（yes/no，是否获取 MIME 类型，默认yes）
- 目标路径：
-
service_facts（采集系统服务状态 Facts）
- 核心功能：专门采集所有系统服务的运行状态（
running/stopped/failed）和开机启动状态（enabled/disabled/masked） - 结果存储：信息存入
ansible_facts.services字典变量，可通过ansible_facts.services['nginx.service'].state获取指定服务运行状态、ansible_facts.services['sshd.service'].status获取开机启动状态 - 兼容性：自动适配 Systemd、Upstart、SysVinit 等主流服务管理系统，无需手动指定服务类型
- 核心功能：专门采集所有系统服务的运行状态（
3. 监控告警与检测
-
wait_for（等待资源就绪，常用于服务启动监控）
- 等待对象：
- 端口监听：
port（目标端口，如80、3306）+host（目标主机，默认localhost） - 文件状态：
path（目标文件路径，如/var/run/nginx.pid） - 进程PID：
pid（进程ID，需结合register从其他任务获取）
- 端口监听：
- 超时与重试：
timeout（超时时间，默认 300 秒，超时则任务失败）、delay（开始等待前的延迟时间，如5秒，避免资源未开始初始化导致误判）、retries（重试次数，默认无限重试直到超时） - 状态判断：
state（started等待端口监听/进程启动、present等待文件存在、absent等待文件删除） - 应用场景：部署 Nginx 后等待 80 端口就绪再执行健康检查、数据库启动后等待
/var/run/mysqld/mysqld.sock存在再执行初始化 SQL
- 等待对象：
-
sensu_check（Sensu 监控检查配置，社区模块）
- 检查基础配置：
name（Sensu 检查名称，如check_nginx_process）、command（监控执行命令，如check-process.rb -p nginx -w 2 -c 1，表示进程数低于1报警、低于2警告） - 执行频率：
interval（检查间隔时间，单位秒，如60表示每分钟检查一次） - 告警分发：
subscribers（订阅该检查的客户端列表，如["web-server", "app-server"]）、handlers（触发告警时的处理程序，如email、slack、pagerduty） - 状态控制：
state（present新增检查配置、absent删除检查配置） - 依赖：需在目标主机提前部署 Sensu Client 并配置与 Sensu Server 通信
- 检查基础配置：
六、云服务与存储类
1. AWS 云服务模块
-
ec2（EC2 实例管理）
- 实例基础配置：
image（AMI 镜像 ID，如ami-0c55b159cbfafe1f0对应 Amazon Linux 2）、instance_type（实例规格，如t2.micro、c5.large）、key_name（SSH 密钥对名称，用于登录实例） - 网络配置：
vpc_subnet_id（子网 ID，如subnet-12345678）、security_group_ids（安全组 ID 列表，如["sg-87654321"]）、associate_public_ip_address（yes/no，是否分配公网 IP） - 存储配置：
volumes（EBS 卷配置，格式为[{"device_name": "/dev/sda1", "volume_size": 20, "volume_type": "gp2"}]，支持 gp2/gp3/io1 等卷类型） - 状态控制：
state（present创建实例、absent删除实例、running启动实例、stopped停止实例） - 初始化：
user_data（实例启动脚本，支持 cloud-init 格式，如#!/bin/bash\nyum install -y nginx，用于实例初始化）
- 实例基础配置：
-
aws_s3（S3 存储桶与对象管理）
- 存储桶操作：
bucket（桶名，需全局唯一）、state（present创建桶、absent删除桶）、region（AWS 地域，如us-east-1、ap-beijing-1）、tags（桶标签，如{"Environment": "production", "Project": "app"}） - 对象操作：
- 上传：
mode: put+src（本地文件路径，如/tmp/data.csv） +object（S3 中对象路径，如data/202405.csv） - 下载：
mode: get+object（S3 对象路径） +dest（本地存储路径，如/tmp/download.csv） - 删除：
mode: delete+object（S3 对象路径） - 列出：
mode: list+prefix（对象路径前缀，如data/2024，仅列出该前缀下的对象）
- 上传：
- 权限控制：
aws_access_key/aws_secret_key（AWS 访问密钥，或通过环境变量、IAM 角色自动获取，推荐使用 IAM 角色避免硬编码密钥）
- 存储桶操作：
-
rds（RDS 数据库实例管理）
- 实例配置：
db_instance_identifier（实例名，如prod-mysql）、engine（数据库引擎，如mysql、postgres、sqlserver-ex）、engine_version（引擎版本，如8.0对应 MySQL 8.0） - 规格与存储：
db_instance_class（实例规格，如db.t3.small）、allocated_storage（存储大小，单位 GB，如50）、storage_type（存储类型，如gp2、io1） - 账号配置：
master_username（管理员用户名，如admin）、master_user_password（管理员密码，建议用ansible-vault加密存储） - 网络与安全：
vpc_security_group_ids（安全组 ID 列表）、db_subnet_group_name（DB 子网组名，需提前创建） - 状态控制：
state（present创建实例、absent删除实例、running启动实例、stopped停止实例）
- 实例配置：
2. 存储管理
-
mount（文件系统挂载与持久化）
- 挂载基础信息：
path（挂载点路径，如/mnt/data，需提前创建目录）、src（设备/共享路径，如/dev/sdb1（本地磁盘）、//192.168.1.100/share（Windows 共享）、192.168.1.101:/data（NFS 共享）） - 文件系统类型：
fstype（如ext4、xfs（本地磁盘）、cifs（Windows 共享）、nfs（NFS 共享）） - 状态控制：
mounted：立即挂载，并写入/etc/fstab实现开机自动挂载unmounted：立即卸载，且从/etc/fstab中移除配置present：仅写入/etc/fstab，不立即挂载absent：从/etc/fstab中移除配置，不影响当前挂载状态
- 挂载参数：
opts（挂载选项，如defaults,noatime（本地磁盘，禁用访问时间更新）、username=user,password=pass（CIFS 共享，指定登录账号密码）、rw,sync（NFS 共享，读写/同步模式））
- 挂载基础信息：
-
lvg（逻辑卷组管理）
- 卷组基础：
vg（卷组名，如vg_data）、pvs（物理卷列表，如["/dev/sdb", "/dev/sdc"]，需提前初始化物理卷pvcreate） - 状态控制：
state（present创建卷组、absent删除卷组（需先删除逻辑卷）、extended扩展卷组（添加新物理卷，如pvs: "/dev/sdd"）） - 扩展参数：
force（yes/no，扩展卷组时强制添加物理卷，忽略“物理卷属于其他卷组”等警告，默认no）
- 卷组基础：
-
lvol（逻辑卷管理）
- 逻辑卷基础：
lv（逻辑卷名，如lv_app）、vg（所属卷组名，如vg_data） - 大小配置：
size（逻辑卷大小，支持绝对值（如50G、100M）和相对值（如100%FREE表示使用卷组所有剩余空间、+20G表示在现有基础上增加 20G）） - 状态控制：
state（present创建逻辑卷、absent删除逻辑卷（需先卸载文件系统）、resized调整逻辑卷大小（需确保文件系统支持在线扩容，如 ext4/xfs）） - 扩展参数：
force（yes/no，调整大小时强制操作，默认no；扩容前建议备份数据，缩容需先缩小文件系统）
- 逻辑卷基础：
3. 其他云平台模块
-
azure_rm_virtualmachine（Azure 虚拟机管理）
- 实例配置：
name（虚拟机名，如prod-web-01）、resource_group（资源组名，如prod-resource-group）、vm_size（实例规格，如Standard_D2s_v3） - 镜像配置：
image（镜像参数，格式为{"publisher": "Canonical", "offer": "UbuntuServer", "sku": "20.04-LTS", "version": "latest"}，或使用自定义镜像 ID） - 网络配置：
virtual_network_name（虚拟网络名）、subnet_name（子网名）、public_ip_allocation_method（公网 IP 分配方式，Dynamic动态分配、Static静态分配） - 认证配置：
admin_username（管理员用户名）、admin_password（密码，或ssh_public_keys指定 SSH 公钥） - 状态控制：
state（present创建实例、absent删除实例、started启动实例、stopped停止实例）
- 实例配置：
-
google.cloud.gcp_compute_instance（GCP 计算实例管理）
- 实例配置：
name（实例名）、zone（可用区，如us-central1-a）、machine_type（实例类型，如n1-standard-1） - 镜像配置：
boot_disk（启动磁盘，格式为{"source_image": "debian-cloud/debian-11", "size_gb": 20}，指定镜像和磁盘大小） - 网络配置：
network_interfaces（网卡配置，如[{"network": "default", "access_configs": [{"name": "External NAT"}]}]，配置网络和公网访问） - 认证配置：
service_account_email（服务账号邮箱，用于权限控制）、credentials_file（GCP 凭证文件路径，或通过环境变量GOOGLE_APPLICATION_CREDENTIALS指定） - 状态控制：
state（present创建实例、absent删除实例、running启动实例、stopped停止实例）
- 实例配置：
七、通用工具与命令类
1. 命令执行模块（核心差异：Shell 特性支持）
-
command（非交互式执行命令，无 Shell 特性）
- 命令内容：
cmd（执行的命令，如ls /opt、cat /etc/hosts、systemctl status nginx） - 条件跳过：
creates（若指定文件存在则跳过命令，如creates: /tmp/init.flag，用于避免重复执行初始化命令）、removes（若指定文件不存在则跳过命令，如removes: /etc/nginx/nginx.conf，用于仅在配置文件存在时执行操作） - 执行环境：
chdir（执行命令前切换到目标目录，如chdir: /opt/app，避免命令路径依赖问题） - 限制：不支持管道（
|）、重定向（>/>>/<）、环境变量（$HOME/$PATH）、通配符（*/?）等 Shell 特性，需复杂语法时用shell模块
- 命令内容：
-
shell（交互式执行命令，支持 Shell 特性）
- 命令内容：
cmd（支持 Shell 语法的命令，如ps aux | grep nginx（管道）、echo "test" > /tmp/file.txt（重定向）、echo $HOME（环境变量）、ls /opt/*.log（通配符）） - 通用参数：
chdir、creates、removes（同command模块） - 扩展参数：
executable（指定 Shell 解释器，如/bin/bash、/bin/sh，默认使用目标主机$SHELL或/bin/sh） - 风险提示：因支持 Shell 语法，需避免命令注入风险（如不直接拼接用户输入的变量，需用
quote过滤器转义，如cmd: "echo {{ user_input | quote }}"）
- 命令内容：
-
raw（无 Python 依赖，直接执行原始命令）
- 适用场景：目标主机未安装 Python 时（Ansible 绝大多数模块依赖 Python，
raw模块通过 SSH 直接执行命令，无需 Python 环境），常用于初始化 Python（如raw: "yum install -y python3"或apt install -y python3） - 命令内容：
args（命令字符串，如raw: "ssh-keygen -t rsa -N '' -f ~/.ssh/id_rsa"） - 限制：不支持 Ansible 变量插值（需手动用 Shell 变量，如
raw: "echo $ENV_VAR"）、无结构化结果返回（仅返回命令输出文本，无法直接提取关键信息）、不支持creates/removes等条件参数
- 适用场景：目标主机未安装 Python 时（Ansible 绝大多数模块依赖 Python，
2. 脚本与程序执行
-
script（在目标主机执行控制节点本地脚本）
- 脚本路径：
script（控制节点上的脚本路径，如./scripts/install_nginx.sh、/opt/ansible/scripts/init_db.sh，Ansible 会自动将脚本传输到目标主机临时目录并执行） - 脚本参数：
args（传递给脚本的参数，如args: "arg1 arg2 --env production"，脚本内通过$1/$2/$3接收） - 执行环境：
chdir（执行脚本前切换到目标主机的指定目录，如chdir: /opt/app，脚本内相对路径基于此目录） - 优势：无需手动拷贝脚本到目标主机，减少文件传输步骤；支持任意脚本类型（Shell、Python、Perl 等，需脚本头部指定解释器，如
#!/bin/bash）
- 脚本路径：
-
command_shell（社区模块，灵活切换执行模式）
- 核心参数：
command（命令内容）、use_shell（yes/no，是否启用 Shell 特性，默认no，即command模式；设为yes则切换为shell模式） - 通用参数：
chdir、creates、removes（同command/shell模块） - 应用场景：需根据变量动态切换命令执行模式时（如
use_shell: "{{ use_complex_syntax | default('no') }}"，当use_complex_syntax为yes时启用 Shell 特性）
- 核心参数：
3. 变量与结果处理
-
set_fact（定义/修改 Facts 变量）
- 变量定义：支持多种数据类型，格式为
key=value：- 字符串：
set_fact: app_version="1.0.0" - 数字：
set_fact: max_connections=1000 - 布尔值：
set_fact: is_production={{ env == 'prod' }}（通过 Jinja2 表达式计算布尔值） - 列表：
set_fact: web_servers=["192.168.1.10", "192.168.1.11", "192.168.1.12"] - 字典：
set_fact: db_config={"host": "db.example.com", "port": 3306, "user": "admin"}
- 字符串：
- 动态计算：支持 Jinja2 过滤器和表达式，如
set_fact: total_memory_gb="{{ ansible_memtotal_mb | int / 1024 | round(1) }}G"（将内存从 MB 转为 GB 并保留1位小数） - 作用域：定义的变量属于 Facts 范畴，在当前 Play 内所有任务可见，可通过
{{ 变量名 }}直接引用，优先级高于普通 Play 变量
- 变量定义：支持多种数据类型，格式为
-
debug（输出调试信息，用于 Playbook 排错）
- 输出方式：
- 自定义消息：
msg（自定义文本，支持变量插值，如debug: msg="当前环境：{{ env }}, 应用版本：{{ app_version }}"） - 变量详情：
var（输出指定变量的完整结构，包括嵌套层级，如debug: var=db_config，会显示字典db_config的所有键值对） - 格式化输出：
verbosity（调试级别，0-4，级别越高输出越详细，默认 0；设为 1 时，需执行 Playbook 加-v参数才显示，如ansible-playbook -v site.yml）
- 自定义消息：
- 应用场景：验证变量值是否符合预期（如检查 Inventory 变量是否正确加载）、查看任务执行结果（如
register注册的命令输出、stat模块采集的文件信息）、定位条件判断逻辑问题（如debug: msg="条件成立"when: is_production）
- 输出方式：
七、通用工具与命令类（补充）
4. 条件与循环控制辅助模块
-
with_items/with_list（循环迭代，Ansible 2.5+ 推荐用
loop替代）-
核心功能：遍历列表数据，为每个元素执行一次任务，适用于批量操作（如批量安装软件、批量创建文件）
-
基础用法：
loop: "{{ 列表变量 }}"（替代旧版with_items），任务内通过{{ item }}引用当前元素-
示例1（批量安装软件）：
- name: 批量安装依赖包 apt: name: "{{ item }}" state: present loop: "{{ dependencies }}" # dependencies 为列表变量：["curl", "git", "vim"] loop_control: label: "安装 {{ item }}" # 自定义循环日志标签，增强可读性 -
示例2（批量创建文件）：
- name: 批量创建配置文件 file: path: "/etc/{{ item }}" state: touch mode: 0644 loop: ["app.conf", "db.conf", "log.conf"]
-
-
扩展用法：
loop: "{{ query('inventory_hostnames', 'web_servers') }}"（结合 Inventory 插件，遍历指定组的主机名）
-
-
with_dict/loop + dict2items（字典迭代）
-
核心功能：遍历字典类型数据，获取键（
key）和值（value），适用于批量配置键值对相关场景（如批量设置环境变量、批量创建用户并指定 UID） -
基础用法：通过
loop: "{{ 字典变量 | dict2items }}"转换字典为列表，任务内通过{{ item.key }}/{{ item.value }}引用键和值-
示例（批量创建用户并指定 UID）：
- name: 批量创建用户（指定 UID） user: name: "{{ item.key }}" uid: "{{ item.value }}" state: present loop: "{{ user_uid_map | dict2items }}" # user_uid_map 为字典：{"alice": 1001, "bob": 1002, "charlie": 1003} loop_control: label: "创建用户 {{ item.key }}（UID: {{ item.value }}）"
-
-
-
when（条件判断）
-
核心功能：根据条件决定任务是否执行，支持布尔值、比较运算、逻辑运算、Facts 变量判断等，实现任务的动态适配
-
常用条件场景：
- 基于操作系统：
when: ansible_os_family == "Debian"（仅 Debian/Ubuntu 执行 apt 安装）、when: ansible_distribution == "CentOS"（仅 CentOS 执行 yum 操作） - 基于变量值：
when: env == "production"（生产环境执行某任务）、when: app_version is version("2.0.0", ">=")（版本号大于等于 2.0.0 时执行） - 基于任务结果：
when: stat_result.stat.exists（文件存在时执行）、when: command_result.rc == 0（命令执行成功时执行，rc为返回码，0 表示成功） - 逻辑组合：
when: ansible_os_family == "RedHat" and ansible_memtotal_mb > 2048（RedHat 系统且内存大于 2G 时执行）
- 基于操作系统：
-
示例（按系统选择包管理器）：
- name: Debian 系列安装 nginx apt: name: nginx state: present when: ansible_os_family == "Debian" - name: RedHat 系列安装 nginx yum: name: nginx state: present when: ansible_os_family == "RedHat"
-
5. 加密与安全模块
-
ansible-vault（文件加密，非 Playbook 模块，属 Ansible 命令行工具，常用于加密敏感文件）
- 核心功能：加密/解密 Ansible 敏感文件（如含密码的变量文件、Inventory 文件），避免敏感信息明文存储
- 常用命令：
- 创建加密文件：
ansible-vault create secrets.yml（交互式设置密码，创建后通过文本编辑器写入敏感内容） - 编辑加密文件：
ansible-vault edit secrets.yml（输入密码后编辑，保存后自动重新加密） - 加密已有明文文件：
ansible-vault encrypt plain.yml（将明文文件plain.yml加密为加密文件） - 解密文件（临时）：
ansible-vault decrypt secrets.yml --output=plain_secrets.yml（解密为明文文件plain_secrets.yml，谨慎使用） - 执行含加密文件的 Playbook：
ansible-playbook -i inventory.yml site.yml --ask-vault-pass（执行时交互式输入 vault 密码）或--vault-password-file=vault_pass.txt（从文件读取密码，需确保文件权限为 0600）
- 创建加密文件：
- 应用场景：存储数据库密码、云服务密钥、SSH 私钥等敏感信息，如
secrets.yml中定义db_password: "EncryptedPassword123"，Playbook 中通过include_vars: secrets.yml加载并引用
-
openssl_privatekey（生成 OpenSSL 私钥）
-
核心功能：在目标主机生成 RSA/ECC 私钥，用于 SSL/TLS 证书配置（如 Nginx HTTPS、API 服务加密）
-
核心参数：
path：私钥存储路径，如/etc/nginx/ssl/server.keysize：RSA 密钥长度，如2048或4096（推荐 4096 位增强安全性）type：密钥类型，RSA（默认）或ECC（椭圆曲线加密，效率更高）mode：私钥文件权限，如0600（仅属主可读，必须严格限制权限）state：present（确保私钥存在，不存在则生成）、absent（删除私钥）
-
示例（生成 Nginx HTTPS 私钥）：
- name: 生成 Nginx HTTPS 私钥（4096 位 RSA） openssl_privatekey: path: /etc/nginx/ssl/server.key size: 4096 mode: 0600 state: present
-
-
openssl_certificate（生成/签署 SSL 证书）
-
核心功能：生成自签名证书、CSR（证书签名请求）或通过 CA 签署证书，配合
openssl_privatekey实现 HTTPS 配置 -
核心参数：
path：证书存储路径，如/etc/nginx/ssl/server.crtprivatekey_path：对应私钥路径，如/etc/nginx/ssl/server.key（与私钥关联）provider：证书生成方式，selfsigned（自签名，适用于测试/内部服务）、csr（生成 CSR 文件，用于向公共 CA 申请证书）、certificate_authority（通过自建 CA 签署证书）subject：证书主题信息，字典格式，如{"CN": "example.com", "O": "MyCompany", "C": "CN", "ST": "Beijing", "L": "Beijing"}（CN 为域名，必须与服务访问域名一致）
-
示例（生成自签名 HTTPS 证书）：
- name: 生成 Nginx HTTPS 自签名证书 openssl_certificate: path: /etc/nginx/ssl/server.crt privatekey_path: /etc/nginx/ssl/server.key provider: selfsigned subject: CN: example.com O: MyWebService C: CN state: present
-
八、特殊场景模块
1. Windows 系统管理模块
-
win_package（Windows 软件安装）
-
核心功能：在 Windows 主机安装 MSI 安装包或 exe 安装程序，支持静默安装
-
核心参数：
name：软件名称（用于标识已安装状态，如"7-Zip 23.01 (x64)"）path：安装程序路径（本地路径或网络共享路径，如C:\installers\7z2301-x64.msi、\\fileserver\installers\Notepad++.exe）product_id：MSI 包的 Product ID（可选，用于精准判断是否已安装，可通过msiexec /i 安装包.msi /qb! /log install.log安装后从注册表或日志获取）arguments：安装参数（静默安装参数，如 MSI 用/qn /norestart，exe 用/S或/verysilent，需参考软件安装文档）state：present（安装）、absent（卸载，仅支持 MSI 包）
-
示例（安装 7-Zip MSI 包）：
- name: Windows 安装 7-Zip win_package: name: 7-Zip 23.01 (x64) path: C:\temp\7z2301-x64.msi arguments: /qn /norestart # 静默安装，不重启 state: present
-
-
win_service（Windows 服务管理）
-
核心功能：管理 Windows 系统服务（启动/停止/重启/设置开机启动），类似 Linux 的
service模块 -
核心参数：
name：服务名称（需用服务的“服务名称”而非“显示名称”，可通过services.msc查看，如"wuauserv"对应“Windows Update”服务）state：started（启动）、stopped（停止）、restarted（重启）、reloaded（重载，部分服务支持）start_mode：开机启动模式，auto（自动）、manual（手动）、disabled（禁用）
-
示例（启动并设置 Windows Update 服务为自动）：
- name: 启动 Windows Update 服务并设为自动启动 win_service: name: wuauserv state: started start_mode: auto
-
-
win_copy（Windows 本地/远程文件拷贝）
-
核心功能：在 Windows 主机间或控制节点与 Windows 主机间拷贝文件，类似 Linux 的
copy模块 -
核心参数：
src：源路径（控制节点路径或 Windows 主机本地路径，如./files/win_config.ini、C:\temp\old_config.ini）dest：目标路径（Windows 主机路径，如C:\ProgramData\app\config.ini）remote_src：yes/no（yes表示源路径在目标 Windows 主机本地，no表示源路径在控制节点）force：yes/no（yes表示目标文件存在时强制覆盖，no表示仅在目标文件不存在时拷贝）
-
示例（从控制节点拷贝配置文件到 Windows 主机）：
- name: 拷贝配置文件到 Windows 主机 win_copy: src: ./files/app_config.ini dest: C:\Program Files\MyApp\config.ini force: yes
-
2. 数据库操作模块
-
mysql_db（MySQL 数据库管理）
-
核心功能：创建/删除 MySQL 数据库、导入 SQL 文件，需提前在目标主机安装
PyMySQL或mysqlclientPython 库（通过pip模块安装） -
核心参数：
name：数据库名（如"app_db"）state：present（创建数据库）、absent（删除数据库，谨慎使用）、import（导入 SQL 文件）login_user：MySQL 登录用户名（如"root"）login_password：MySQL 登录密码（建议通过ansible-vault加密存储）login_host：MySQL 服务器地址（默认localhost，远程数据库需指定）login_port：MySQL 端口（默认3306）target：state=import时，指定 SQL 文件路径（如/opt/sql/init_db.sql）
-
示例（创建 MySQL 数据库并导入初始化 SQL）：
- name: 安装 PyMySQL（MySQL 模块依赖） pip: name: PyMySQL state: present - name: 创建 app_db 数据库 mysql_db: name: app_db state: present login_user: root login_password: "{{ mysql_root_password }}" # 加密变量 login_host: localhost - name: 导入 app_db 初始化 SQL mysql_db: name: app_db state: import target: /opt/sql/init_app_db.sql login_user: root login_password: "{{ mysql_root_password }}"
-
-
postgresql_db（PostgreSQL 数据库管理）
-
核心功能：类似
mysql_db，用于 PostgreSQL 数据库的创建/删除/导入，依赖psycopg2Python 库 -
核心参数：
name：数据库名（如"pg_app_db"）state：present（创建）、absent（删除）、import（导入 SQL）login_user：PostgreSQL 登录用户（如"postgres"）login_password：PostgreSQL 登录密码login_host：PostgreSQL 服务器地址（默认localhost）login_port：PostgreSQL 端口（默认5432）target：state=import时的 SQL 文件路径
-
示例（创建 PostgreSQL 数据库）：
- name: 安装 psycopg2（PostgreSQL 模块依赖） apt: name: python3-psycopg2 state: present when: ansible_os_family == "Debian" - name: 创建 pg_app_db 数据库 postgresql_db: name: pg_app_db state: present login_user: postgres login_password: "{{ pg_postgres_password }}"
-
九、模块使用注意事项与最佳实践
1. 模块依赖检查
-
Python 依赖：绝大多数 Ansible 模块依赖 Python（如
yum/apt/file/copy等），目标主机需提前安装 Python（Linux 通常预装，最小化系统需手动安装：CentOS 用yum install -y python3，Ubuntu 用apt install -y python3） -
模块专属依赖：部分模块需额外安装依赖库，如：
-
数据库模块：
mysql_db依赖PyMySQL/mysqlclient，postgresql_db依赖psycopg2 -
云服务模块：
aws_s3/ec2依赖boto3/botocore，azure_rm_virtualmachine依赖azure-mgmt-compute -
建议在 Playbook 开头通过
pip模块统一安装依赖，如：- name: 安装 AWS 模块依赖 pip: name: boto3 state: present
-
2. 幂等性保障（核心原则）
-
定义：Ansible 模块需支持“幂等性”——即多次执行同一任务，结果一致且无副作用（如安装软件时，已安装则跳过；创建文件时，已存在则不重复创建）
-
关键参数：
state: present（确保存在，已存在则跳过）而非state: latest（强制升级，可能有风险）creates/removes（command/shell模块实现幂等性的关键，避免重复执行命令）force: no（copy/template模块默认值，仅在源文件变化时覆盖目标文件）
-
反例（非幂等）：
- name: 非幂等命令（每次执行都会追加内容） shell: echo "test" >> /tmp/log.txt # 多次执行会重复追加，无幂等性 -
正例（幂等）：
- name: 幂等命令（仅在文件不存在时执行） shell: echo "test" > /tmp/log.txt creates: /tmp/log.txt # 文件存在则跳过，实现幂等性
3. 安全性最佳实践
- 敏感信息加密：使用
ansible-vault加密含密码、密钥的文件，避免明文存储；执行 Playbook 时通过--ask-vault-pass或安全的密码文件（权限 0600）传递密码 - 最小权限原则：避免用
root执行所有任务，可通过become: yes按需提权，或在 Inventory 中指定普通用户+sudo权限 - 避免命令注入：
shell模块使用变量时，通过quote过滤器转义，如cmd: "echo {{ user_input | quote }}" - 模块优先于 raw/shell：能用官方模块（如
file/copy/service）实现的功能，优先不用raw/shell，减少脚本依赖和安全风险
posted on 2025-11-05 11:13 chuchengzhi 阅读(2) 评论(0) 收藏 举报
浙公网安备 33010602011771号