基础设施即代码 / 系统课时
用 ansible-lint 建立质量门槛
用 ansible-lint 建立质量门槛
这一课把 ansible-lint 从“偶尔手工检查”变成项目质量门槛:同一套规则同时约束本地提交与 CI,提前发现语法、命名、幂等性和高风险写法,并让违规提交以明确的非零退出码被阻断。
学习目标
- 为 Ansible 项目建立可版本化的
ansible-lint规则配置 - 识别命名、FQCN、幂等性和命令滥用等常见违规
- 在持续集成中把 lint 失败转换为合并阻断条件
先把质量门槛写成项目规则
质量门槛的关键不是“规则越多越好”,而是所有开发者和 CI 使用同一份配置。把配置放在仓库根目录后,检查结果就不依赖个人命令习惯;提交前能发现的问题,也不会等到生产执行时才暴露。
下面是一份适合作为起点的 .ansible-lint。production profile 用于采用较严格的规则集合,strict: true 让警告也能影响最终退出状态。
profile: production
strict: true
exclude_paths:
- .cache/这是配置文件,不会单独产生控制台输出。验证方法是在仓库根目录运行 ansible-lint;若项目内容满足规则,进程应以退出码 0 结束。不要一开始就大量加入 skip_list,否则门槛会逐渐退化成“只检查容易通过的部分”。
用一个最小 Playbook 验证规则
下面的 Playbook 使用完整限定集合名,并让模块自身表达期望状态,避免用任意 Shell 命令模拟包管理和服务管理。假设 inventory.yml 已定义 web 主机组。
- name: Configure web service
hosts: web
become: true
tasks:
- name: Ensure nginx is installed
ansible.builtin.package:
name: nginx
state: present
- name: Ensure nginx is running
ansible.builtin.service:
name: nginx
state: started
enabled: true先做语法检查,确认 YAML 能被 Ansible 解析为合法 Playbook。
ansible-playbook -i inventory.yml --syntax-check playbooks/site.yml预期输出
playbook: playbooks/site.yml再执行 lint,并只把最终退出状态打印出来,避免不同版本的摘要文案影响验证。
ansible-lint playbooks/site.yml >/dev/null && echo "lint_exit=0"预期输出
lint_exit=0如果命令没有打印这行,说明 lint 返回了非零状态,应先阅读它报告的 rule ID 和文件位置,再修改内容,而不是直接跳过规则。
重点看幂等性与风险模式
ansible-lint 的价值不仅是格式统一。它会把很多“语法合法但工程上危险”的写法提前暴露出来。最常见的几类问题可以按下面思路处理:
- 任务缺少清晰名称时,补充能描述期望状态的
name,让日志和失败位置可读。 - 模块使用短名称时,优先改为
ansible.builtin.*或对应 Collection 的 FQCN,减少名称冲突和来源歧义。 command、shell这类任务无法自动判断是否发生变更时,应改用具备幂等语义的模块;确实只能执行命令时,再用可靠条件定义changed_when。- 能用专用模块完成的文件、服务、软件包操作,不要退化成 Shell 命令,否则 check mode、变更判断和错误处理都会变差。
把同一检查接入持续集成
下面的 GitHub Actions 工作流在推送到 main 和创建 Pull Request 时执行语法检查与 lint。真实项目应把 ansible-lint 版本固定在开发依赖或锁文件中,确保本地与 CI 不因版本漂移产生不同结果。
name: ansible-quality
on:
pull_request:
push:
branches:
- main
jobs:
lint:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Install ansible-lint
run: python -m pip install ansible-lint
- name: Check playbook syntax
run: ansible-playbook -i inventory.yml --syntax-check playbooks/site.yml
- name: Run ansible-lint
run: ansible-lint playbooks/site.yml这个配置的生效行为很直接:任一步骤返回非零状态,lint job 就失败,分支保护可以据此拒绝合并。验证时故意制造一个已知违规并提交测试分支,确认 CI 失败;修复违规后再次推送,确认检查恢复为通过。
处理例外而不是关闭门槛
确有历史债务时,优先把例外记录到 .ansible-lint-ignore,让违规仍可见并逐步偿还;只有确认某条规则不适用于整个项目时,才考虑全局跳过。质量门槛最终要保证三件事:规则随仓库版本化、本地与 CI 结果一致、任何例外都有可追踪的理由。