一、起源:人工登录逐台操作的问题
1.1 逐台操作产生的三类问题
在主机数量进入两位数之后,通过 SSH 登录逐台执行命令的方式会稳定地产生三类问题。
不一致
同一份配置在多台主机上的落地结果取决于操作时的因素:
- 执行顺序与时机不同,中途被打断的任务只在一部分主机上完成
- 操作者依据记忆或旧笔记执行,参数、路径、权限取值出现偏差
- 主机自身的初始状态不同(已装的软件版本、已有的配置文件内容),同一条命令产生不同结果
- 配置修改只覆盖了本次涉及的主机,遗漏了同类角色的其他主机
不一致的后果是同类主机行为分化,故障只在部分实例上出现,排查时需要逐台比对。
不可追溯
人工操作的过程记录通常只保留在终端历史或沟通记录中:
- 缺少"谁在何时改动了哪台主机的哪个文件"的完整记录
- 变更内容没有版本化,无法对比变更前后的差异
- 无变更记录与故障时间的对齐依据,定位只能依靠猜测
- 交接时无法说明某台主机的配置为何与同类主机不同
无法批量验证
变更之后的核对同样依赖逐台登录:
- 期望状态与当前状态之间没有可重复执行的比对手段
- 只能抽查若干台,无法给出全量结论
- 部分主机的配置被重复执行或被人为回退后,没有机制发现
1.2 脚本化与配置管理的边界
用脚本封装批量操作是第一步。常见的形态是在控制机上用循环遍历主机列表,逐台通过 SSH 执行相同的命令:
for host in $(cat hosts.txt); do
ssh "${host}" 'sudo sed -i "s/^#Port 22/Port 2222/" /etc/ssh/sshd_config'
done
脚本解决了"重复输入"的问题,但引入了新的缺陷:
- 缺少幂等判断。同一脚本执行两次,追加类操作会产生重复内容,
sed类操作的结果取决于当前文件内容 - 缺少结果聚合。循环输出中混杂多台主机的日志,失败主机需要人工翻找,且脚本通常不会因单台失败而中断或汇总退出码
- 缺少抽象。主机分组、变量、模板、敏感信息都写在脚本内部,新增一类主机需要复制并修改脚本
- 缺少状态语义。脚本不区分"已符合期望"与"本次发生了变更",无法判断变更影响面
配置管理工具解决的是上述四点,其与脚本化的边界在于:
- 适合配置管理:主机可通过 SSH 或同类通道批量连接、配置项可描述为期望状态、需要周期性地复核与收敛
- 不适合配置管理:需要交互式确认的一次性操作、无远程通道的设备初始化、图形界面操作、必须依赖人工判断的应急处置
二、原理
2.1 无代理架构
Ansible 采用无代理(agentless)模型,被控端不需要安装常驻进程。
连接模型
控制端通过 SSH 连接被控端,连接参数(地址、端口、用户、密钥)在 inventory 或命令参数中声明。所有任务由控制端发起,被控端不主动回连,也不需要开放除 SSH 之外的端口。
模块执行方式
每执行一个任务,控制端把对应的模块代码打包传输到被控端的临时目录(默认位于远端用户的 ~/.ansible/tmp),在该目录内以脚本方式执行,执行完成后删除临时目录。模块执行结果以 JSON 形式返回控制端,由控制端汇总输出。
实际执行过程可在目标端观察:
# 控制端执行
ansible web -m ping -vvv
# 被控端临时目录(执行期间可见)
ls -la ~/.ansible/tmp/
代价与收益
| 维度 | 无代理架构的表现 |
|---|---|
| 部署成本 | 被控端无需安装与升级代理,无需常驻进程占用内存 |
| 端口要求 | 仅需 SSH,不额外开放端口,网络策略与现有运维通道一致 |
| 单任务开销 | 每次任务需建立连接并传输模块,任务粒度越细开销占比越高 |
| 依赖条件 | 依赖 SSH 可达与远端具备可用的 Python 解释器 |
| 规模上限 | 并发受控制端进程数与远端负载约束,需要通过分批与优化参数控制 |
连接开销可通过 SSH 连接复用缓解,在 ansible.cfg 中启用:
[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
pipelining:省去模块文件的落盘步骤,减少一次往返,要求被控端的requiretty已关闭ControlPersist:在多个任务间复用同一条 SSH 连接,任务数量越多收益越明显
2.2 幂等与期望状态
命令式脚本与声明式任务的差别
- 命令式脚本描述"做什么动作":追加一行配置、把文件复制过去、执行一条命令。动作是否已经完成、是否会产生重复副作用,由脚本作者自行判断
- 声明式任务描述"最终状态是什么":该文件存在且属主为 X、该软件包处于已安装状态、该服务处于运行且开机自启状态。是否执行动作由模块判断
changed 与 ok 的含义
模块接收参数后,先读取当前状态,与期望状态比对,仅在两者不一致时执行变更:
ok:当前状态已符合期望,本次未产生任何变更changed:当前状态与期望不符,本次执行了变更动作failed:模块判定执行失败,后续行为取决于错误处理策略skipped:条件判断(when)或检查模式(--check)导致任务未执行
第二个字段就是判断幂等性的直接依据:同一 playbook 连续执行两次,第二次的变更项应全部为 ok。若第二次仍出现 changed,说明对应任务不具备幂等性。
# 第二次执行时全部为 ok
ansible-playbook -i inventory site.yml
重复执行的判定依据
幂等判定由模块实现承担,不同模块的判定维度不同:
| 模块 | 判定依据 |
|---|---|
file | 路径是否存在、类型、属主属组、权限位是否一致 |
copy / template | 源内容与目标内容的校验和是否一致 |
apt / dnf | 软件包是否已安装、版本是否满足要求 |
service / systemd | 单元是否处于期望的 active 与 enabled 状态 |
user / group | 账户是否存在、UID、主组、附加组、Shell 是否一致 |
lineinfile | 目标行是否已存在且内容一致 |
command 与 shell 模块不具备幂等性,它们不判断当前状态,每次执行都返回 changed。改造方式见第三章第 3 小节。
2.3 目录与作用域
配置管理代码需要明确的目录约定,否则变量来源与任务归属会随规模增长而失控。常用职责划分如下:
| 位置 | 职责 |
|---|---|
| inventory | 主机清单与分组,定义"对哪些主机执行" |
| group_vars/ | 按分组划分的变量,定义"某一类主机的公共参数" |
| host_vars/ | 按单台主机划分的变量,定义"某一台主机的差异参数" |
| roles/<role>/tasks/ | 该角色要执行的任务序列 |
| roles/<role>/handlers/ | 该角色声明的处理器,由任务 notify 触发 |
| roles/<role>/templates/ | Jinja2 模板文件,渲染后下发 |
| roles/<role>/files/ | 静态文件,原样下发 |
| roles/<role>/defaults/ | 角色默认变量,可被外部覆盖,优先级最低 |
| roles/<role>/vars/ | 角色内部变量,优先级高于绝大多数外部变量 |
| roles/<role>/meta/ | 角色依赖关系声明 |
| collections/ | 第三方模块、插件与角色的打包集合 |
行为参数集中在 ansible.cfg 中,避免把路径与并发参数写在命令行上:
[defaults]
inventory = ./inventory
roles_path = ./roles
remote_user = ops
host_key_checking = True
forks = 20
retry_files_enabled = False
[privilege_escalation]
become = True
become_method = sudo
become_user = root
作用域原则:
- 与主机身份无关的公共参数放
group_vars/all - 与角色相关的参数放该分组的
group_vars/<组名>.yml - 单台主机的差异(地址、容量、编号)放
host_vars/<主机名>.yml - 角色自身的默认值放
defaults/main.yml,使其可被调用方覆盖;只有确定不允许覆盖的参数才放vars/main.yml
2.4 变量优先级与覆盖关系
同一变量名可在多处定义,最终取值由优先级决定。由低到高的常见层级如下,同层级内后出现者覆盖先出现者:
| 顺序 | 来源 |
|---|---|
| 1 | 角色 defaults/main.yml |
| 2 | inventory 的 group_vars/all |
| 3 | inventory 的 group_vars/<组名> |
| 4 | inventory 的 host_vars/<主机名> |
| 5 | play 中的 vars 与 vars_files |
| 6 | 角色 vars/main.yml |
| 7 | block 级 vars 与 tasks 中的 vars |
| 8 | set_fact 与 register 注册的变量 |
| 9 | 命令行 -e 或 --extra-vars 传入的变量 |
排查变量取值问题的顺序:
- 确认是否通过
-e传入了同名变量,该层优先级最高且常被忽略 - 查看
host_vars是否覆盖了group_vars中的取值 - 检查同名变量是否在多处定义,尤其是角色
vars/main.yml覆盖了调用方传入的值 - 确认模板或任务中引用的变量名拼写与作用域一致
# 查看某台主机的最终变量取值
ansible-inventory -i inventory --host web01
# 查看全部变量的合并结果
ansible-inventory -i inventory --list
# 任务执行时输出变量值(临时排查用)
ansible-playbook -i inventory site.yml --limit web01 -e "debug_var=1"
- name: 排查变量取值
hosts: web01
tasks:
- name: 输出目标变量
ansible.builtin.debug:
var: app_config_path
2.5 模板与处理器
模板机制
Jinja2 模板用于生成内容随变量变化的目标文件。模板文件放在角色的 templates/ 目录,通过 template 模块下发:
- name: 下发服务配置
ansible.builtin.template:
src: app.conf.j2
dest: /etc/myapp/app.conf
owner: root
group: root
mode: "0644"
notify: 重启 myapp
# templates/app.conf.j2 渲染结果示例
listen_port = {{ app_port | default(8080) }}
worker_num = {{ ansible_processor_vcpus * 2 }}
log_level = {{ 'debug' if app_debug | default(false) else 'info' }}
{% for node in app_backends %}
backend = {{ node }}
{% endfor %}
模板相关要点:
template模块渲染后与目标文件比对校验和,只有内容不同才产生changed,因此无需在任务中自行编写差异判断- 变量未定义时渲染报错,可选参数使用
| default(值)提供兜底 {{ }}中的表达式由 Jinja2 解析,{% %}控制流程;{# #}为注释,不出现在渲染结果中- 模板中使用的事实变量(如
ansible_processor_vcpus)来自被控端采集,可通过gather_facts: false关闭采集以减少开销
handler 的触发条件与执行时机
handler 是一类特殊任务,默认不在 tasks 列表中被直接调用,而是由其他任务的 notify 触发:
- 触发条件是被 notify 的那个任务返回
changed。任务返回ok时,handler 不被触发 - 执行时机默认在 play 的所有任务执行完成后,而非任务返回 changed 的当场
- 同名 handler 在一次 play 中被多次触发时只执行一次,因此多个配置文件的修改只会引起一次服务重启
- name: 应用配置
hosts: web
handlers:
- name: 重启 myapp
ansible.builtin.systemd:
name: myapp
state: restarted
tasks:
- name: 下发主配置
ansible.builtin.template:
src: app.conf.j2
dest: /etc/myapp/app.conf
notify: 重启 myapp
- name: 下发证书
ansible.builtin.copy:
src: server.crt
dest: /etc/myapp/server.crt
notify: 重启 myapp
需要在 play 中途强制执行已触发的 handler 时,使用 flush_handlers 任务插入到指定位置;在 play 报错中断时需要执行 handler,可将其放入 always 块。
失败与重试策略
- name: 等待服务端口就绪
ansible.builtin.wait_for:
host: 127.0.0.1
port: 8080
timeout: 30
register: wait_result
until: wait_result is succeeded
retries: 5
delay: 5
until:重试判定条件,满足该条件即结束重试retries:最大重试次数,超出后任务判定失败delay:两次重试之间的等待秒数- 重试适用于依赖外部系统就绪的场景(等待端口监听、等待数据库可连、等待接口返回成功状态),不适用于掩盖持续存在的失败
三、实现
3.1 inventory 编写
静态清单与分组
INI 格式的清单以分组划分为主,组可嵌套:
# inventory/hosts
[web]
web01 ansible_host=10.0.1.11
web02 ansible_host=10.0.1.12
[db]
db01 ansible_host=10.0.2.11 ansible_port=2222
[db:vars]
ansible_user=dbadmin
[prod:children]
web
db
[prod:vars]
ansible_ssh_private_key_file=~/.ssh/id_ed25519_prod
YAML 格式适合定义结构较复杂的变量:
all:
children:
web:
hosts:
web01:
ansible_host: 10.0.1.11
app_role: frontend
web02:
ansible_host: 10.0.1.12
app_role: frontend
db:
hosts:
db01:
ansible_host: 10.0.2.11
ansible_port: 2222
vars:
ansible_user: dbadmin
常用连接参数:
| 参数 | 作用 |
|---|---|
ansible_host | 实际连接地址,与清单中的主机别名区分 |
ansible_port | SSH 端口,非 22 时必填 |
ansible_user | 登录用户 |
ansible_ssh_private_key_file | 私钥路径 |
ansible_python_interpreter | 远端 Python 解释器路径,用于系统自带 Python 版本与默认路径不一致的环境 |
ansible_ssh_common_args | 附加 SSH 参数,常用于声明跳板机 |
跳板机
通过 ProxyJump 复用 OpenSSH 的跳转能力,被控端无需额外配置:
[bastion:vars]
ansible_ssh_common_args=-o ProxyJump=ops@10.0.0.10
动态清单
主机数量随弹性伸缩变化、或已有 CMDB 与云平台维护主机信息时,静态清单需要人工同步,容易与实际资源脱节。动态清单由脚本或插件在每次执行时查询数据源生成主机列表。
适用场景:
- 云主机按标签或安全组划分,实例随扩缩容增删
- 主机信息由 CMDB 或资产系统统一维护,存在唯一的事实来源
- 环境频繁重建,主机名或地址不具备稳定性
需要权衡的点:
- 动态清单引入了对上游接口的依赖,接口不可用时无法执行
- 查询结果的缓存时间需与变更频率匹配,缓存过长会导致新主机不可见
- 分组规则由标签或元数据推导,标签管理不规范时分组结果不可控
# 验证动态清单解析结果
ansible-inventory -i ./inventory/dynamic.py --graph
# 按标签限定范围
ansible-playbook -i ./inventory/dynamic.py site.yml --limit 'tag_role_web'
3.2 playbook 组织
任务、条件与循环
- name: 部署应用
hosts: web
become: true
vars:
app_port: 8080
tasks:
- name: 安装依赖包
ansible.builtin.apt:
name: "{{ item }}"
state: present
loop:
- nginx
- python3
- curl
- name: 仅在 Debian 系主机执行
ansible.builtin.apt:
name: net-tools
state: present
when: ansible_os_family == "Debian"
- name: 查询已加载的内核模块
ansible.builtin.command: lsmod
register: lsmod_result
changed_when: false
check_mode: false
- name: 模块未加载时的提示
ansible.builtin.debug:
msg: "nf_conntrack 未加载"
when: "'nf_conntrack' not in lsmod_result.stdout"
when:条件表达式,为假时任务被跳过并记为skippedloop:遍历列表,循环变量为item;with_dict、with_nested等写法已归并到loop配合过滤器使用register:把任务返回值保存为变量,供后续任务引用(stdout、rc、changed等字段)changed_when: false:显式声明该只读命令不产生变更,避免污染变更统计
错误处理
- name: 带恢复逻辑的部署
hosts: web
tasks:
- name: 部署与回滚
block:
- name: 停止应用
ansible.builtin.systemd:
name: myapp
state: stopped
- name: 下发新版本
ansible.builtin.copy:
src: myapp.jar
dest: /opt/myapp/myapp.jar
- name: 启动应用
ansible.builtin.systemd:
name: myapp
state: started
rescue:
- name: 记录失败
ansible.builtin.command: logger -t deploy "部署失败,执行回滚"
- name: 恢复上一版本
ansible.builtin.copy:
src: myapp.jar.bak
dest: /opt/myapp/myapp.jar
remote_src: true
- name: 重新启动应用
ansible.builtin.systemd:
name: myapp
state: restarted
always:
- name: 输出部署结束标记
ansible.builtin.debug:
msg: "部署流程结束"
block:把一组任务视为一个单元,便于统一施加条件与错误处理rescue:block中任一任务失败时执行,用于回滚与记录always:无论成功、失败或跳过都会执行,用于清理与收尾
ignore_errors 的取舍
ignore_errors: true 使任务失败后继续执行后续任务,适用于:
- 探测类任务,失败本身是有效信息(例如检查某个可选组件是否存在)
- 已知在部分主机上必然失败、且失败无副作用的清理动作
不宜使用的情形:
- 任务失败会导致后续任务基于错误状态继续执行,最终失败点远离根因
- 用于掩盖尚未定位的报错,使失败从执行结果中消失
- 替代
failed_when:需要自定义失败判定时,用failed_when明确表达条件,比忽略错误后再判断更清晰
- name: 自定义失败判定
ansible.builtin.command: /opt/myapp/health-check.sh
register: hc
failed_when: "'OK' not in hc.stdout"
any_errors_fatal: true 作用于 play 级别,任一主机失败即中断整个 play,适合不允许部分成功的不一致场景。
标签与分段执行
- name: 配置 web 主机
hosts: web
tasks:
- name: 安装软件包
ansible.builtin.apt:
name: nginx
state: present
tags: [packages]
- name: 下发配置
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
tags: [config]
# 只执行指定标签的任务
ansible-playbook -i inventory site.yml --tags config
# 跳过指定标签
ansible-playbook -i inventory site.yml --skip-tags packages
# 列出将要执行的任务清单
ansible-playbook -i inventory site.yml --list-tasks
标签用于按变更内容分段执行,常见划分方式为安装、配置、服务、检查四类。标签应沿任务粒度标注,避免把整个角色的任务打上同一个标签。
3.3 常用模块与场景
包管理
- name: 安装软件包
ansible.builtin.apt:
name:
- nginx
- logrotate
state: present
update_cache: true
- name: 移除软件包
ansible.builtin.apt:
name: telnet
state: absent
- name: 清理无用依赖
ansible.builtin.apt:
autoremove: true
state: present表示处于已安装状态,版本不做约束state: latest表示升级到最新版本,会使每次执行的变更结果依赖源中版本,降低可重复性update_cache对应先刷新索引,跨发行版的模块名与参数差异需按目标系统选择(apt与dnf)- 包管理命令与源配置的细节参见 ../packageManagement/apt.html
文件与模板下发
- name: 创建目录
ansible.builtin.file:
path: /opt/myapp
state: directory
owner: myapp
group: myapp
mode: "0750"
- name: 下发静态文件
ansible.builtin.copy:
src: files/app.jar
dest: /opt/myapp/app.jar
owner: myapp
group: myapp
mode: "0644"
backup: true
- name: 确保配置行存在
ansible.builtin.lineinfile:
path: /etc/myapp/app.conf
regexp: '^max_connections='
line: 'max_connections=500'
backup: true在覆盖前保留一份带时间戳的副本,便于回退lineinfile的regexp用于定位已有行并替换,避免重复追加;成块的配置使用blockinfile配合标记,或改用模板整体渲染- 权限使用字符串形式(
"0644"),避免 YAML 把前导零解析为八进制数以外的含义
服务与 systemd
- name: 管理应用服务
ansible.builtin.systemd:
name: myapp
enabled: true
state: started
- name: 单元文件变更后重载并重启
ansible.builtin.systemd:
name: myapp
daemon_reload: true
state: restarted
- 单元文件的依赖关系、
daemon-reload的执行时机与故障排查参见 ../processManagement/systemd.html - 仅修改单元文件而不触发
daemon_reload时,systemd 使用的仍是旧配置
用户与权限
- name: 创建服务账户
ansible.builtin.user:
name: myapp
system: true
shell: /usr/sbin/nologin
create_home: false
- name: 部署运维公钥
ansible.posix.authorized_key:
user: ops
key: "{{ lookup('file', 'files/ops_ed25519.pub') }}"
state: present
- name: 独立 sudoers 子配置
ansible.builtin.copy:
content: "ops ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart myapp\n"
dest: /etc/sudoers.d/myapp-ops
owner: root
group: root
mode: "0440"
validate: "visudo -cf %s"
validate在写入前对临时文件执行校验,校验失败则不替换目标文件,用于规避 sudoers 或配置文件语法错误导致的不可用- sudoers 规则语法与权限要求参见 ../useAndGroupManagement/user_and_group_management.html
命令模块的幂等改造
command 与 shell 每次执行都返回 changed,需要显式改造:
- name: 初始化数据目录(幂等)
ansible.builtin.command: /opt/myapp/bin/init.sh
args:
creates: /var/lib/myapp/initialized
- name: 仅当配置缺失时执行迁移
ansible.builtin.shell: |
set -o pipefail
/opt/myapp/bin/migrate.sh
args:
removes: /var/lib/myapp/legacy.lock
creates:目标路径已存在时跳过任务removes:目标路径不存在时跳过任务- 判断类命令使用
changed_when: false;命令确实产生变更但不返回标准结果时,用changed_when按输出判定
- name: 按输出判定是否产生变更
ansible.builtin.shell: /opt/myapp/bin/reload.sh
register: reload_out
changed_when: "'reloaded' in reload_out.stdout"
脚本自身的健壮性写法(set -euo pipefail、trap 清理、参数校验)参见 ../shell/shell_execution.html 中的脚本健壮性与生产实践小节。
定时任务管理
- name: 每日备份任务
ansible.builtin.cron:
name: "myapp backup"
minute: "0"
hour: "3"
user: root
job: "/usr/local/sbin/backup.sh >> /var/log/backup.log 2>&1"
state: present
name作为任务标识写入 crontab 注释,用于后续定位与删除,必填- 使用
cron模块管理而非直接编辑 crontab,避免与其他来源的任务相互覆盖 - cron 与 systemd timer 的机制差异、任务未执行的排查顺序参见 ../processManagement/scheduled_tasks_and_timers.html
3.4 批量执行与风险控制
高危 提醒:批量执行会把一次变更同时施加到清单内的全部主机,错误的内容会被等比例放大。执行前的兜底方式为:先以 --list-hosts 与 --limit 确认目标范围、以 --check --diff 预演变更内容、以 serial 将批次控制在可回滚的规模、确保配置目录处于版本控制且可回退,并在变更窗口内保留可直接回滚的上一版本。
预演
# 仅检查会产生哪些变更,不做实际修改
ansible-playbook -i inventory site.yml --check
# 检查并输出文件差异
ansible-playbook -i inventory site.yml --check --diff
# 预演结果中 changed 表示"将会变更",不代表可以全部自动应用
--check 依赖模块对检查模式的支持。command、shell 等模块默认跳过执行,需配合 creates、removes 或 check_mode: false 才能在预演中给出有意义的结果。
范围控制
# 确认目标主机清单
ansible-playbook -i inventory site.yml --list-hosts
# 限定主机或分组
ansible-playbook -i inventory site.yml --limit 'web01'
ansible-playbook -i inventory site.yml --limit 'web:!web03'
# 从失败主机开始重跑(retry 文件需启用)
ansible-playbook -i inventory site.yml --limit @site.retry
批次与失败控制
- name: 分批更新
hosts: web
serial: 3
max_fail_percentage: 20
tasks:
- name: 更新应用
ansible.builtin.apt:
name: myapp
state: latest
serial:每批处理的主机数量或比例,批次之间互不影响,适合需要灰度验证的场景max_fail_percentage:单批失败比例超过该值时中断整个 play,避免继续向剩余批次扩散forks:控制并发进程数,直接决定控制端同时连接的主机数量
本地执行与委派
- name: 在控制端生成汇总清单
hosts: web
tasks:
- name: 汇总各主机版本
ansible.builtin.command: /usr/bin/myapp --version
register: ver
changed_when: false
- name: 写入本地汇总文件
ansible.builtin.copy:
content: "{{ ansible_play_hosts | map('extract', hostvars) | list | length }} 台主机已检查\n"
dest: /var/log/ansible/summary.txt
delegate_to: 127.0.0.1
run_once: true
delegate_to:把任务委派到指定主机执行,常用 127.0.0.1 表示控制端run_once: true:只在第一台主机上执行一次,适合只需执行一遍的注册动作
失败中断与继续的取舍
| 策略 | 适用场景 | 风险 |
|---|---|---|
| 默认中断该主机,继续其他主机 | 主机之间相互独立,部分失败不影响其余主机 | 清单内出现状态分化,需要按失败清单补做 |
any_errors_fatal: true | 变更要求全量一致,部分成功即为失败 | 单台问题导致整体不落地,已变更的主机需要单独处理 |
serial 分批 | 需要控制影响面与验证节奏 | 执行时间随批次数线性增长 |
ignore_errors: true | 探测类任务 | 后续任务可能基于错误状态继续执行 |
3.5 敏感信息
vault 加密
# 加密整个变量文件
ansible-vault encrypt group_vars/all/vault.yml
# 加密单个字符串,输出可直接粘贴到变量文件中
ansible-vault encrypt_string --name 'db_password' 'S3cretValue'
# 查看与编辑
ansible-vault view group_vars/all/vault.yml
ansible-vault edit group_vars/all/vault.yml
# 更换加密口令
ansible-vault rekey group_vars/all/vault.yml
加密后的文件内容以固定头部标识,可安全纳入版本控制:
# group_vars/all/vault.yml
$ANSIBLE_VAULT;1.1;AES256
66386439653...
执行时提供口令的方式:
# 交互输入
ansible-playbook -i inventory site.yml --ask-vault-pass
# 从文件读取
ansible-playbook -i inventory site.yml --vault-password-file ~/.vault_pass
# 从外部密钥管理系统动态获取(脚本输出口令)
ansible-playbook -i inventory site.yml \
--vault-password-file ./scripts/fetch-vault-pass.sh
- 口令文件不得提交到版本库,需加入忽略清单并限制文件权限(
chmod 600) - 口令脚本从密钥管理系统或环境变量取值,避免把口令固化在脚本内部
--vault-id可为不同环境指定不同口令来源,实现生产与测试的密钥隔离
密钥轮换与审计
轮换流程:
- 在密钥管理系统中新增一版口令,保留旧口令可解
- 对受影响的 vault 文件执行
ansible-vault rekey,按环境分批进行 - 更新各环境的口令来源(口令文件或取值脚本)
- 验证新口令可解密并完成一次部署
- 从密钥管理系统中吊销旧口令
审计要点:
- 禁止在任务参数中直接写明文口令,
command、shell的-p类参数会出现在进程列表中,也会被日志记录 - 对包含敏感参数的模块使用
no_log: true,避免返回值在标准输出与日志中回显
- name: 初始化数据库账号
ansible.builtin.command: /opt/myapp/bin/set-password.sh
environment:
DB_PASSWORD: "{{ vault_db_password }}"
no_log: true
- 定期核对加密文件清单与实际使用范围,清理已下线的密钥
- 排查阶段使用
-vvv会增加输出内容,no_log之外的任务参数可能被打印,该参数只应在受控环境临时使用
3.6 配置漂移治理
配置漂移指主机当前状态与声明的期望状态不一致,来源通常有三类:
- 应急排障时的手工修改,事后未回写到配置管理代码
- 其他自动化手段或软件包升级覆盖了受管文件
- 配置管理代码已更新,但部分主机未执行最新的 playbook
以检查模式定期复核
# 全量复核,输出将会被收敛的差异
ansible-playbook -i inventory site.yml --check --diff > /var/log/ansible/drift-$(date +%F).log 2>&1
# 仅复核配置类任务
ansible-playbook -i inventory site.yml --check --diff --tags config
复核结果的处理方式:
- 输出中存在
changed项即表示该主机存在漂移,--diff给出了具体差异内容 - 需要区分"预期外的漂移"与"代码已领先于主机"两类情况:前者需要确认手工变更是否应保留,后者属于正常的待发布变更
- 差异日志按日期归档,与上一周期结果对比,定位新增漂移项
巡检与配置管理的衔接
巡检脚本负责发现差异(配置文件校验、计划任务清单比对、软件包版本核对),配置管理负责把差异收敛到期望状态,两者的分工如下:
| 环节 | 承担方 | 输出 |
|---|---|---|
| 发现差异 | 巡检脚本按周期执行 | 结构化记录与差异清单 |
| 判定取舍 | 人工确认 | 需回写的配置变更或需覆盖的漂移 |
| 收敛状态 | playbook 执行 | 变更记录与执行结果 |
| 验证结果 | 再次以检查模式复核 | 全量一致的结论 |
巡检项的分类、频率与结果归档方式参见 ../monitoring/inspection_and_health_check.html,本节的复核命令可作为其配置完整性类检查项的实现手段。
执行巡检复核时同样受批量执行风险约束:--check 不产生变更,可以全量执行;一旦去掉 --check 转为收敛,需按前述范围控制与分批策略执行。
3.7 与流水线和监控的衔接
触发方式
| 触发方式 | 适用场景 | 需要控制的事项 |
|---|---|---|
| 人工执行 | 首次部署、应急变更 | 执行人、执行范围、变更记录 |
| 定时执行(cron 或 systemd timer) | 定期收敛配置漂移 | 与业务高峰错开,避免与其他任务争抢资源 |
| 流水线触发 | 代码合并后的自动化发布 | 环境与分支的对应关系、审批环节 |
| 事件触发(Webhook) | 资源创建完成后接入配置 | 上游事件的幂等性与重复投递处理 |
# /etc/systemd/system/ansible-converge.timer
[Unit]
Description=每日以检查模式复核配置漂移
[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true
[Install]
WantedBy=timers.target
对应单元文件的编写方式与定时器机制参见 ../processManagement/scheduled_tasks_and_timers.html。
# 流水线中的执行与记录示例
ANSIBLE_LOG_PATH=/var/log/ansible/run-$(date +%Y%m%d-%H%M%S).log \
ansible-playbook -i inventory site.yml --limit "${TARGET_GROUP}"
echo "exit=$?"
执行记录
- 控制端日志统一落盘并纳入轮转,保留周期与变更审计要求匹配
- 一次执行需可回溯:目标范围、执行的代码版本、每台主机的 changed 与 failed 明细、执行人与时间
- 代码版本与执行记录关联,通过提交标识标记本次部署对应的代码版本
- 排查失败主机时按主机名过滤日志,而不是翻看整体输出
变更与告警联动
- 变更窗口内对受影响主机的告警设置静默或抑制,避免重启引起的短时抖动产生噪声
- 变更完成后主动执行验证任务(端口监听、接口返回、进程状态),把结论作为执行结果的一部分
- 变更引起的持续告警不应被静默掩盖,静默需设置明确的结束时间
- 把执行失败接入告警通道,避免失败任务只留在日志中无人查看
- 监控侧的规则构成与抑制机制参见 ../monitoring/monitoring_and_alerting.html
3.8 常见问题
首次连接与主机密钥
- 首次连接时被控端的主机密钥不在本地信任列表中,默认配置下会被拒绝
- 处置方式为提前采集并写入信任列表,或在受控环境下临时关闭校验
# 提前采集主机密钥
ssh-keyscan -t ed25519 10.0.1.11 >> ~/.ssh/known_hosts
# 重建机器后的旧密钥冲突,按行删除后重新采集
ssh-keygen -R 10.0.1.11
- 长期关闭主机密钥校验会失去中间人攻击的防护,仅在首次批量初始化阶段临时使用
- 主机密钥冲突的典型报错为
REMOTE HOST IDENTIFICATION HAS CHANGED,重装系统或更换主机后必然出现,需确认地址复用是预期行为后再清理旧记录
sudo 与 become 配置
# ansible.cfg
[privilege_escalation]
become = True
become_method = sudo
become_user = root
- name: 整体提权
hosts: web
become: true
tasks:
- name: 以服务账户执行
ansible.builtin.command: /opt/myapp/bin/task.sh
become: true
become_user: myapp
- 提权用户需在 sudoers 中具备对应授权,缺少授权时报错为
Missing sudo password或is not in the sudoers file - 使用免密提权时,前提是该账户的授权范围已按最小权限收敛,
NOPASSWD: ALL会放大凭据泄露的影响面 - 部分发行版默认开启
requiretty,非交互式会话下提权被拒,需在 sudoers 中取消该项或启用 pipelining - sudoers 授权与提权审计参见 ../useAndGroupManagement/user_and_group_management.html
远端 Python 解释器缺失
- 模块以 Python 执行,远端无可用解释器时报错为
/usr/bin/python: not found - 处置方式为显式声明解释器路径,或在安装解释器之前使用不依赖 Python 的模块
# 按主机或分组声明
[web:vars]
ansible_python_interpreter=/usr/bin/python3
- name: 安装 Python 解释器(不依赖 Python 的模块)
hosts: newhosts
gather_facts: false
tasks:
- name: 通过 raw 模块执行包安装
ansible.builtin.raw: apt-get update && apt-get install -y python3
changed_when: false
raw直接通过 SSH 执行命令,不经过模块机制,因此不受解释器缺失影响,适合初始化阶段gather_facts依赖远端 Python,解释器不可用时必须先关闭事实采集
并发过大导致目标端负载升高
forks决定控制端同时连接的主机数;单台主机上若同时执行多个任务,也会叠加资源开销- 现象为目标端负载升高、包管理器锁冲突(
Could not get lock)、服务重启引起连接中断 - 包管理相关的锁冲突成因与处置参见 ../packageManagement/apt.html 的常见问题小节
- 控制方式为降低
forks取值、使用serial分批、把批量任务安排在业务低峰期执行
编码与时区差异
- 模板中的中文内容在目标端出现乱码,通常源于文件编码不一致,需统一为 UTF-8 并在目标端确认 locale 配置
- 时间戳类变量在控制端与目标端时区不同时产生偏移,需要在模板中显式指定时区,或统一使用 UTC 记录
- 时区不一致对日志时间线与认证校验的影响参见 ../troubleshooting/fault_case_library.html 中时间偏移案例的定位过程
- 远端采集的系统信息受 locale 影响时,可在任务中通过
environment显式设置:
- name: 统一执行环境
ansible.builtin.command: /opt/myapp/bin/report.sh
environment:
LANG: C.UTF-8
TZ: UTC
四、总结
- 人工逐台操作的问题集中在不一致、不可追溯与无法批量验证三处,脚本化解决了重复输入,但缺少幂等、结果聚合、变量抽象与状态语义
- 无代理架构以 SSH 为唯一通道,模块传输到被控端临时目录执行后删除;代价是每任务一次连接的开销与对远端 Python 的依赖,收益是无需部署与升级常驻进程
- 幂等判定由模块完成,
ok表示已符合期望状态,changed表示本次产生了变更;连续两次执行第二次应全部为ok - 目录划分对应作用域:inventory 定义目标范围,
group_vars与host_vars定义变量差异,roles 内部按任务、处理器、模板、文件与默认值分层 - 变量取值由优先级决定,
-e传入的值最高;排查顺序为命令行传参、host_vars与group_vars的覆盖关系、角色内部变量的同名定义 - handler 由
notify触发且仅在任务返回changed时生效,默认在 play 末尾统一执行,同名 handler 只执行一次 - 批量执行的风险控制手段为
--check --diff预演、--limit限定范围、serial分批与max_fail_percentage限制失败比例;危险动作需预先确认目标范围与回滚路径 - 敏感信息以 vault 加密后纳入版本控制,口令从外部密钥管理系统获取,轮换后吊销旧口令,含敏感参数的任务使用
no_log - 配置漂移的治理路径为定期以检查模式复核、人工确认取舍、由 playbook 收敛、再次复核确认一致;巡检负责发现,配置管理负责收敛
- 常见问题集中在首次连接的主机密钥校验、提权授权与
requiretty、远端解释器缺失、并发与分批控制、以及编码与时区差异五处 - 相关专题参见 ../packageManagement/apt.html、../processManagement/systemd.html、../useAndGroupManagement/user_and_group_management.html、../monitoring/inspection_and_health_check.html、./infrastructure_as_code.html