基础设施即代码 / 系统课时

用 ansible-lint 建立质量门槛

用 ansible-lint 建立质量门槛

这一课把 ansible-lint 从“偶尔手工检查”变成项目质量门槛:同一套规则同时约束本地提交与 CI,提前发现语法、命名、幂等性和高风险写法,并让违规提交以明确的非零退出码被阻断。

学习目标

  • 为 Ansible 项目建立可版本化的 ansible-lint 规则配置
  • 识别命名、FQCN、幂等性和命令滥用等常见违规
  • 在持续集成中把 lint 失败转换为合并阻断条件

先把质量门槛写成项目规则

质量门槛的关键不是“规则越多越好”,而是所有开发者和 CI 使用同一份配置。把配置放在仓库根目录后,检查结果就不依赖个人命令习惯;提交前能发现的问题,也不会等到生产执行时才暴露。

下面是一份适合作为起点的 .ansible-lint。production profile 用于采用较严格的规则集合,strict: true 让警告也能影响最终退出状态。

yaml
profile: production
strict: true
exclude_paths:
  - .cache/

这是配置文件,不会单独产生控制台输出。验证方法是在仓库根目录运行 ansible-lint;若项目内容满足规则,进程应以退出码 0 结束。不要一开始就大量加入 skip_list,否则门槛会逐渐退化成“只检查容易通过的部分”。

用一个最小 Playbook 验证规则

下面的 Playbook 使用完整限定集合名,并让模块自身表达期望状态,避免用任意 Shell 命令模拟包管理和服务管理。假设 inventory.yml 已定义 web 主机组。

yaml
- 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。

bash
ansible-playbook -i inventory.yml --syntax-check playbooks/site.yml

预期输出

text
playbook: playbooks/site.yml

再执行 lint,并只把最终退出状态打印出来,避免不同版本的摘要文案影响验证。

bash
ansible-lint playbooks/site.yml >/dev/null && echo "lint_exit=0"

预期输出

text
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 不因版本漂移产生不同结果。

yaml
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 结果一致、任何例外都有可追踪的理由。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ansible-lint 建立质量门槛

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通