摘要
本文记录一次将 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 资产到 NetBoxreadonly_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 健康巡检。
自动化运维的关键不是把命令藏进脚本,而是让执行入口、执行边界和执行结果都变得可控、可追溯、可复用。