摘要

本文记录一次将 Ansible Linux 健康巡检接入 GitLab CI/CD 的完整实践:从控制机代码入库、Windows 本地协作、GitLab Runner 注册,到按环境触发巡检、保存 Markdown/JSON 报告,并总结 Runner 证书、版本、项目绑定和空 Playbook 等真实踩坑经验。


背景:为什么要把 Ansible 巡检放进 GitLab Pipeline

在自动化运维落地过程中,Linux 巡检通常一开始是手工执行:

ansible-playbook -i inventories/netbox.yml \
  playbooks/02-vm-ops/inspect/linux_health_check.yml \
  --limit env_dmztest

这种方式能跑,但长期维护会遇到几个问题。

1、巡检结果分散在控制机本地,不方便统一下载和追溯。

2、执行命令依赖个人记忆,参数容易漏。

3、任务无法定时化。

4、遇到多环境巡检时,也缺少统一入口。

5、更重要的是,当 Ansible Playbook 逐渐增多,团队需要一个标准方式来区分“巡检、CMDB 同步、平台回填、策略检查”等不同任务。

因此,本次目标是将已有的 Ansible 巡检接入 GitLab Pipeline,实现:

  • 支持手动触发
  • 支持定时触发
  • 支持按环境触发
  • 支持保存巡检报告为 GitLab Artifacts
  • 支持后续扩展 NetBox、华为云、主机运维等更多任务

最终形成的流程是:

本地 Cursor 编辑
  -> git push 到 GitLab
  -> GitLab Runner 在 ansible-new 控制机执行
  -> Ansible 使用 NetBox 动态 inventory 巡检
  -> 生成 JSON / Markdown 报告
  -> GitLab Artifacts 归档

项目结构设计

控制机上的 Git 仓库根目录是 /data/ansible-deploy,本地 Windows 也克隆一份同构目录:

ansible-deploy/
├── .gitlab-ci.yml
├── ansible.cfg
├── inventories/
│   └── netbox.yml
├── playbooks/
│   ├── 01-infra-automation/
│   │   └── netbox/
│   │       ├── sync_ecloud_ecs_to_netbox.py
│   │       └── update_vm_platform_from_facts.yml
│   ├── 02-vm-ops/
│   │   └── inspect/
│   │       ├── linux_health_check.yml
│   │       ├── tasks/
│   │       ├── templates/
│   │       └── vars/
│   ├── 03-middleware-ops/
│   ├── 04-security-baseline/
│   ├── 05-db-ops/
│   ├── 06-backup-ops/
│   ├── 07-k8s-ops/
│   └── 08-network-ops/
├── reports/
├── roles/
└── scripts/

这种组织方式的核心思想是:

playbooks/ 负责按运维领域划分任务入口,roles/ 负责沉淀可复用能力,.gitlab-ci.yml 负责把不同入口编排成可触发的流水线任务。

例如:

02-vm-ops/inspect/linux_health_check.yml

就是 Linux 健康巡检入口。后续中间件、数据库、安全基线等任务可以继续放到对应目录中。

GitLab CI 的设计思路

一个项目里可以有多个 Playbook,但不能让 Runner “自己猜”要跑哪个任务。生产上更推荐:

一个 job 对应一类明确任务

例如:

  • linux_health_inspect:Linux 健康巡检
  • update_vm_platform:回填 NetBox VM 的真实系统平台
  • sync_ecloud_ecs_to_netbox:从华为云同步 ECS 资产到 NetBox
  • readonly_asset_policy_check:只读策略检查

这样做的好处是边界清晰、风险可控、权限容易收敛。尤其是涉及 CMDB 写入、自动修复、改密等操作时,不应该把所有 Playbook 做成一个任意路径变量随便执行。

核心实现:最终版 .gitlab-ci.yml

下面是本次落地后的核心 CI 配置。它使用 ansible-new 这个 Runner tag,并将任务分为 validate、inspect、cmdb、ops 四类。

stages:
  - validate
  - inspect
  - cmdb
  - ops

variables:
  ANSIBLE_INVENTORY: "inventories/netbox.yml"
  INSPECT_PLAYBOOK: "playbooks/02-vm-ops/inspect/linux_health_check.yml"
  INSPECT_ENV: ""
  INSPECT_LIMIT: ""
  INSPECT_EXTRA_VARS: ""
  NETBOX_SYNC_APPLY: "false"

default:
  tags:
    - ansible-new
  before_script:
    - set -euo pipefail
    - cd "$CI_PROJECT_DIR"

validate_ansible_syntax:
  stage: validate
  script:
    - ansible-playbook --syntax-check -i "$ANSIBLE_INVENTORY" "$INSPECT_PLAYBOOK"
    - ansible-playbook --syntax-check -i "$ANSIBLE_INVENTORY" playbooks/01-infra-automation/netbox/update_vm_platform_from_facts.yml
    - ansible-playbook --syntax-check -i "$ANSIBLE_INVENTORY" playbooks/01-infra-automation/readonly_asset_policy_check.yml
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'

linux_health_inspect:
  stage: inspect
  resource_group: linux-health-inspect
  timeout: 2h
  script:
    - |
      report_dir="reports/inspect/gitlab-${CI_PIPELINE_ID}-${CI_JOB_ID}"
      ansible_limit=""

      if [ -n "$INSPECT_LIMIT" ]; then
        ansible_limit="$INSPECT_LIMIT"
      elif [ -n "$INSPECT_ENV" ]; then
        ansible_limit="env_${INSPECT_ENV}"
      fi

      cmd=(
        ansible-playbook
        -i "$ANSIBLE_INVENTORY"
        "$INSPECT_PLAYBOOK"
        -e "inspect_report_dir=${report_dir}"
      )

      if [ -n "$ansible_limit" ]; then
        cmd+=(--limit "$ansible_limit")
      fi

      if [ -n "$INSPECT_EXTRA_VARS" ]; then
        cmd+=(--extra-vars "$INSPECT_EXTRA_VARS")
      fi

      echo "Running: ${cmd[*]}"
      "${cmd[@]}"

      if [ ! -d "$report_dir" ]; then
        echo "Report directory was not generated: $report_dir"
        echo "Check whether the selected inventory limit matched at least one host."
        exit 1
      fi

      mkdir -p ci_artifacts/inspect
      cp -a "${report_dir}/." ci_artifacts/inspect/
      ls -l ci_artifacts/inspect
  artifacts:
    name: "linux-health-${CI_PIPELINE_ID}-${CI_JOB_ID}"
    when: always
    expire_in: 30 days
    paths:
      - ci_artifacts/inspect/
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: on_success
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
      allow_failure: false
    - if: '$CI_PIPELINE_SOURCE == "api" || $CI_PIPELINE_SOURCE == "trigger"'
      when: manual
      allow_failure: false
    - when: manual
      allow_failure: true

update_vm_platform:
  stage: cmdb
  resource_group: netbox-cmdb-update
  timeout: 2h
  script:
    - |
      ansible_limit=""
      if [ -n "$INSPECT_LIMIT" ]; then
        ansible_limit="$INSPECT_LIMIT"
      elif [ -n "$INSPECT_ENV" ]; then
        ansible_limit="env_${INSPECT_ENV}"
      fi

      cmd=(
        ansible-playbook
        -i "$ANSIBLE_INVENTORY"
        playbooks/01-infra-automation/netbox/update_vm_platform_from_facts.yml
      )

      if [ -n "$ansible_limit" ]; then
        cmd+=(--limit "$ansible_limit")
      fi

      echo "Running: ${cmd[*]}"
      "${cmd[@]}"
  rules:
    - when: manual
      allow_failure: false

sync_ecloud_ecs_to_netbox:
  stage: cmdb
  resource_group: netbox-cmdb-update
  timeout: 2h
  script:
    - |
      cmd=(python3 playbooks/01-infra-automation/netbox/sync_ecloud_ecs_to_netbox.py)

      if [ "$NETBOX_SYNC_APPLY" = "true" ]; then
        cmd+=(--apply)
      fi

      echo "Running: ${cmd[*]}"
      "${cmd[@]}"
  rules:
    - when: manual
      allow_failure: false

readonly_asset_policy_check:
  stage: ops
  timeout: 1h
  script:
    - ansible-playbook -i "$ANSIBLE_INVENTORY" playbooks/01-infra-automation/readonly_asset_policy_check.yml
  rules:
    - when: manual
      allow_failure: false

这段配置里最关键的是 linux_health_inspect。它支持两种范围控制方式:

INSPECT_ENV=dmztest

会自动转换为:

--limit env_dmztest

如果想直接使用 Ansible 原生 limit,可以传:

INSPECT_LIMIT=env_dmztest

或者:

INSPECT_LIMIT=@/tmp/alive_vms.txt

其中 INSPECT_LIMIT 优先级高于 INSPECT_ENV。

巡检 Playbook 如何生成报告

巡检 Playbook 里没有再单独写一个 localhost play,而是在 post_tasks 中使用 run_once 和 delegate_to: localhost 生成报告。

post_tasks:
  - name: Mark unreachable hosts in audit
    ansible.builtin.set_fact:
      health_audit:
        host: "{{ inventory_hostname }}"
        ansible_host: "{{ ansible_host | default('') }}"
        inspected_at: "{{ ansible_date_time.iso8601 }}"
        reachable: false
        status: unreachable
        warn_count: 0
        crit_count: 0
        findings: []
        message: "Host unreachable or facts not gathered"
    when: health_audit is not defined

  - name: Generate inspection reports on controller
    run_once: true
    delegate_to: localhost
    become: false
    vars:
      inspect_target_hosts: "{{ ansible_play_hosts_all }}"
      _report_ts: "{{ lookup('pipe', 'TZ=Asia/Shanghai date +%Y%m%dT%H%M%S') }}"
      report_generated_at: "{{ lookup('pipe', 'TZ=Asia/Shanghai date \"+%Y-%m-%d %H:%M:%S CST (UTC+8)\"') }}"
      inspect_all_audits: >-
        {{
          (ansible_play_hosts_all | default([]))
          | map('extract', hostvars, 'health_audit')
          | select('defined')
          | list
        }}
    block:
      - name: Ensure report directory exists
        ansible.builtin.file:
          path: "{{ inspect_report_base }}"
          state: directory
          mode: "0755"

      - name: Build summary counts
        ansible.builtin.set_fact:
          inspect_summary:
            total: "{{ ansible_play_hosts_all | default([]) | length }}"
            audited: "{{ inspect_all_audits | length }}"
            ok: "{{ inspect_all_audits | selectattr('status', 'equalto', 'ok') | list | length }}"
            warn: "{{ inspect_all_audits | selectattr('status', 'equalto', 'warn') | list | length }}"
            crit: "{{ inspect_all_audits | selectattr('status', 'equalto', 'crit') | list | length }}"
            unreachable: "{{ inspect_all_audits | selectattr('status', 'equalto', 'unreachable') | list | length }}"

      - name: Write JSON report
        ansible.builtin.copy:
          dest: "{{ inspect_report_base }}/linux_health_{{ _report_ts }}.json"
          mode: "0644"
          content: "{{ {'summary': inspect_summary | combine({'generated_at': report_generated_at}), 'hosts': inspect_all_audits} | to_nice_json }}"

      - name: Write Markdown report
        ansible.builtin.template:
          src: templates/health_report.md.j2
          dest: "{{ inspect_report_base }}/linux_health_{{ _report_ts }}.md"
          mode: "0644"

这个设计解决了一个很容易踩的坑:如果单独写 hosts: localhost 的第二个 play,当执行命令带 --limit env_dmztest 时,localhost 也可能被过滤掉,导致报告不生成。

报告生成挂在已匹配目标主机的 post_tasks 中执行,再通过 delegate_to: localhost 回到控制机写文件,是更稳妥的写法。

巡检阈值配置

阈值集中放在 playbooks/02-vm-ops/inspect/vars/defaults.yml:

---
inspect_fstypes:
  - ext4
  - ext3
  - xfs
  - btrfs
  - nfs
  - nfs4

inspect_mount_prefixes: []

disk_warn_pct: 80
disk_crit_pct: 90
inode_warn_pct: 80
inode_crit_pct: 90

mem_warn_pct: 85
mem_crit_pct: 95

swap_warn_pct: 50
swap_crit_pct: 80

load_warn_factor: 1.0
load_crit_factor: 2.0

zombie_warn_count: 5
zombie_crit_count: 20

inspect_report_dir: reports/inspect

如果临时调整阈值,可以在 GitLab Pipeline 里传:

INSPECT_EXTRA_VARS=disk_warn_pct=75 disk_crit_pct=85

CI 中会拼接为:

--extra-vars "disk_warn_pct=75 disk_crit_pct=85"

GitLab Runner 注册与证书处理

本次使用的是 Shell Runner,安装在 ansible-new 控制机上。Runner tag 必须与 .gitlab-ci.yml 里的 ansible-new 完全一致。

curl -L --output /usr/local/bin/gitlab-runner \
  https://gitlab-runner-downloads.s3.amazonaws.com/v17.6.1/binaries/gitlab-runner-linux-amd64

chmod +x /usr/local/bin/gitlab-runner

useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
gitlab-runner start
gitlab-runner status

GitLab 使用自签名 HTTPS 证书时,Runner 注册需要显式指定 CA 文件:

mkdir -p /etc/gitlab-runner/certs

cp /data/gitlab-lab/config/ssl/gitlab.crt \
  /etc/gitlab-runner/certs/gitlab.crt

chmod 644 /etc/gitlab-runner/certs/gitlab.crt

gitlab-runner register \
  --url "https://10.255.10.31" \
  --token "glrt-你的token" \
  --tls-ca-file "/etc/gitlab-runner/certs/gitlab.crt"

注册时选择:

executor: shell

注册完成后检查:

gitlab-runner list
gitlab-runner status

手动触发与按环境巡检

在 GitLab 项目中进入:

CI/CD -> Pipelines -> Run pipeline

添加变量:

INSPECT_ENV=dmztest

然后创建 Pipeline。validate_ansible_syntax 会自动执行,linux_health_inspect 可以手动点击运行,也可以通过 schedule 自动运行。

巡检成功后,GitLab Job 会上传 artifact:

ci_artifacts/inspect/

里面包含:

linux_health_<时间戳>.json
linux_health_<时间戳>.md

在 Job 页面可以直接点击 Browse 或 Download 查看报告。

踩坑与避坑指南

坑一:Runner 版本高于 GitLab Server

一开始下载的是 GitLab Runner 最新版,而 GitLab Server 是 17.6.1。虽然不一定立刻不能用,但生产上不建议 Runner 主版本高于 GitLab Server。建议保持同大版本

坑二:自签名证书导致 Runner 注册失败

Runner 注册时报错:

tls: failed to verify certificate:
x509: certificate signed by unknown authority

解决方式是注册时加:

--tls-ca-file "/etc/gitlab-runner/certs/gitlab.crt"

如果之前 Docker Runner 正常,通常说明证书本身已经可用,只是新的 Shell Runner 没带 tls-ca-file 配置。

坑三:Runner 注册到了错误项目

曾经把 runner 绑定到了错误项目,导致 ansible-deploy 项目里看不到可用 Runner。解决方式是到正确项目重新创建 Project Runner,并确认页面显示:

Owner: ansible-deploy
Tag: ansible-new
Status: Online

如果本地出现多个同名 runner,可以查看:

gitlab-runner list

必要时清理 /etc/gitlab-runner/config.toml 中错误的 [[runners]] 段,再重新注册。

坑四:空 Playbook 导致语法检查失败

第一次跑 pipeline 时,validate_ansible_syntax 失败:

ERROR! Empty playbook, nothing to do:
playbooks/01-infra-automation/check-connectivity.yml

原因是 check-connectivity.yml 文件为空,但 CI 已经对它执行了语法检查。

解决方式是:未完成的 Playbook 不要纳入 validate。等文件有真实内容后,再加入 syntax check 和对应 job。

坑五:--limit 会影响报告生成

如果报告生成写成第二个 play:

- name: Generate reports
  hosts: localhost

当执行时带:

--limit env_dmztest

第二个 play 可能因为 localhost 不在 limit 范围内而被跳过。

最终采用:

run_once: true
delegate_to: localhost

这样报告生成逻辑仍然挂在目标主机 play 的 post_tasks 中,不会被单独的 localhost play 过滤掉。

坑六:Git 不跟踪空目录

playbooks/03-middleware-ops 到 08-network-ops 一开始是空目录,因此不会被 Git 提交。

如果想保留目录结构,可以放一个 README.md 或 .gitkeep:

echo "Middleware operations playbooks." > playbooks/03-middleware-ops/README.md

相比 .gitkeep,README.md 更适合团队协作,因为它能说明目录用途。

坑七:Shell Runner 的执行用户问题

Runner 安装时如果使用:

gitlab-runner install --user=gitlab-runner

那么 job 就不是 root 执行,而是 gitlab-runner 用户执行。此时需要确认它有权限访问:

Ansible 命令
inventories/netbox.yml
目标主机 SSH 私钥
NetBox token 或相关环境变量

可以这样测试:

sudo -u gitlab-runner -H bash

cd /data/ansible-deploy

ansible-playbook --version

ansible-inventory -i inventories/netbox.yml --graph

如果短期只想快速跑通,也可以让 Runner 用 root 执行,但要确保 GitLab 项目权限严格控制。

后续优化方向

当前方案已经可以稳定运行,但后续任务变多后,不建议把所有 job 都堆在根 .gitlab-ci.yml 里。

更推荐拆分为:

.gitlab-ci.yml
.gitlab/
└── ci/
    ├── validate.yml
    ├── vm-ops.yml
    ├── infra-automation.yml
    ├── middleware-ops.yml
    ├── security-baseline.yml
    └── db-ops.yml

根 .gitlab-ci.yml 只保留:

include:
  - local: ".gitlab/ci/validate.yml"
  - local: ".gitlab/ci/vm-ops.yml"
  - local: ".gitlab/ci/infra-automation.yml"

等 Linux 巡检逻辑继续增长后,也可以把当前 playbooks/02-vm-ops/inspect/tasks、templates、vars 迁移成 Ansible Role:

roles/
└── linux_health_check/
    ├── defaults/
    ├── tasks/
    ├── templates/
    └── README.md

Playbook 只负责调用:

---
- name: Linux health inspection
  hosts: protocol_ssh
  gather_facts: true
  become: false
  ignore_unreachable: true

  roles:
    - linux_health_check

这会让巡检逻辑更适合长期维护和复用。

总结

这次实践把原本手工执行的 Ansible Linux 巡检,接入到了 GitLab CI/CD 中,最终实现了按环境触发、手动触发、定时触发和报告归档。

整个方案的核心价值在于:

  • NetBox 负责资产和分组
  • Ansible 负责真实巡检执行
  • GitLab CI 负责触发、审计和报告归档
  • GitLab Runner 部署在控制机上,复用已有运维网络和凭据

最终效果是:运维人员不再需要记复杂命令,只需要在 GitLab 页面填入 INSPECT_ENV=dmztest,点击运行,就能完成一次带报告归档的 Linux 健康巡检。

自动化运维的关键不是把命令藏进脚本,而是让执行入口、执行边界和执行结果都变得可控、可追溯、可复用。