摘要:
本文记录了一次将外部 Linux 云主机批量接入 Prometheus + Grafana 的实践过程。方案基于 NetBox 动态 inventory、GitLab CI 和 Ansible,批量安装 node_exporter、process_exporter 与 mysqld_exporter,并自动生成 Prometheus external targets,适合多主机监控接入和标准化运维场景。
背景:为什么要批量安装 Exporter
在 Prometheus 监控体系里,Kubernetes 内部服务通常比较容易接入,但外部云主机、传统虚拟机、数据库服务器就没那么统一了。
这次的目标很明确:把 NetBox 中登记的 Linux 云主机批量接入 Prometheus + Grafana,统一采集三类指标:
node_exporter:采集主机 CPU、内存、磁盘、网络等基础指标,监听9100process_exporter:采集 Java、Nginx、MySQL、Redis 等进程级指标,监听9256mysqld_exporter:采集 MySQL 指标,监听9104
最终希望做到:
- 主机来源不手工维护,直接使用 NetBox 动态 inventory
- exporter 安装过程由 Ansible 批量执行
- GitLab CI 手动触发,避免误操作生产环境
- Prometheus targets 自动生成并写入 Kubernetes Secret
- Grafana 使用现有 Dashboard 直接查看外部主机指标
批量接入监控最怕的不是安装 exporter,而是主机清单、端口、防火墙、Prometheus targets 和后续验证没有形成闭环。
整体方案设计
这套方案的主链路如下:
GitLab CI 手动触发
-> Ansible plan 检查
-> Ansible install 安装 exporter
-> 从 NetBox 动态 inventory 生成 Prometheus targets
-> 更新 Kubernetes Secret additional-scrape-configs
-> 重启 Prometheus StatefulSet
-> 在 Prometheus /targets 和 Grafana 中验证
其中,外部主机的 Prometheus job 名称固定为:
node-exporter
process-exporter
mysqld-exporter
这里有一个很重要的细节:不要随意修改 node-exporter 这个 job 名称。很多 Grafana Node Exporter 默认看板依赖这个 job 名称或相关标签,改名后 PromQL 可能查不到外部主机。
目录与版本规划
本次使用的 Ansible playbook 目录如下:
playbooks/02-vm-ops/monitoring/
├── node_exporter_plan.yml
├── node_exporter_install.yml
├── process_exporter_plan.yml
├── process_exporter_install.yml
├── mysqld_exporter_plan.yml
├── mysqld_exporter_install.yml
├── update_prometheus_targets.yml
├── vars/defaults.yml
└── templates/
├── additional-scrape-configs.yaml.j2
└── additional-scrape-configs-secret.yaml.j2
核心版本和端口统一放在 vars/defaults.yml 中管理:
node_exporter_version: "1.5.0"
node_exporter_archive: "/data/tools/node_exporter-1.5.0.linux-amd64.tar.gz"
node_exporter_listen_address: ":9100"
node_exporter_firewall_port: 9100
process_exporter_version: "0.8.5"
process_exporter_archive: "/data/tools/process-exporter-0.8.5.linux-amd64.tar.gz"
process_exporter_listen_address: ":9256"
process_exporter_firewall_port: 9256
mysqld_exporter_version: "0.15.1"
mysqld_exporter_archive: "/data/tools/mysqld_exporter-0.15.1.linux-amd64.tar.gz"
mysqld_exporter_listen_address: ":9104"
mysqld_exporter_firewall_port: 9104
mysqld_exporter_extra_args: "--collect.info_schema.processlist"
这样做的好处是,后续升级 exporter 版本时,不需要在多个 playbook 里到处改路径和端口。
批量安装 Node Exporter
node_exporter 是主机监控的基础组件,安装逻辑主要包括:
- 检查控制机安装包是否存在
- 跳过无
ansible_host的主机 - 跳过不可达主机
- 跳过非 Linux 或非
amd64架构主机 - 创建系统用户
node_exporter - 解压二进制到
/usr/local/bin/node_exporter - 写入 systemd 服务
- 启动并设置开机自启
- 自动处理
firewalld或ufw - 本机验证
/metrics是否返回 200
核心 systemd 配置如下:
[Unit]
Description=Prometheus Node Exporter
After=network.target
[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter --web.listen-address=:9100
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
安装命令示例:
ansible-playbook -i inventories/netbox.yml \
playbooks/02-vm-ops/monitoring/node_exporter_install.yml \
--limit env_dmztest
安装完成后,可以在目标主机上验证:
systemctl status node_exporter
curl -s http://127.0.0.1:9100/metrics \
| grep -E '^(node_uname_info|node_cpu_seconds_total|node_memory_MemAvailable_bytes)' \
| head
如果这些指标能查到,说明 exporter 本身已经正常工作。接下来还需要确认 Prometheus 是否能从远端访问 9100 端口。
批量安装 Process Exporter
process_exporter 用来补充进程维度指标,比如 Java、Nginx、MySQL、Redis、Kafka 等。它的关键点是配置文件,而不是二进制本身。
示例配置如下:
process_names:
- name: "java"
comm:
- java
- name: "python"
comm:
- python
- python3
- name: "nginx"
comm:
- nginx
- name: "mysqld"
comm:
- mysqld
- mariadbd
- name: "redis"
comm:
- redis-server
- redis
- name: "kafka"
cmdline:
- ".*kafka.*"
systemd 服务配置如下:
[Unit]
Description=Prometheus Process Exporter
After=network.target
[Service]
User=process_exporter
Group=process_exporter
Type=simple
ExecStart=/usr/local/bin/process-exporter --config.path=/etc/process-exporter/config.yml --web.listen-address=:9256
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
安装命令:
ansible-playbook -i inventories/netbox.yml \
playbooks/02-vm-ops/monitoring/process_exporter_install.yml \
--limit env_dmztest
验证方式:
systemctl status process_exporter
curl -s http://127.0.0.1:9256/metrics | grep namedprocess_namegroup
process_exporter 特别适合做进程存活、进程数量、资源占用等补充监控。
批量安装 MySQL Exporter
mysqld_exporter 相比前两个 exporter 更容易踩坑,因为它不只是启动一个 HTTP 服务,还需要能连上本机 MySQL。
本方案默认不自动创建 MySQL 用户,而是要求提前创建采集账号。默认 TCP 连接方式为 127.0.0.1:3306:
CREATE USER IF NOT EXISTS 'mysqld_exporter'@'127.0.0.1' IDENTIFIED BY '<password>' WITH MAX_USER_CONNECTIONS 3;
GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO 'mysqld_exporter'@'127.0.0.1';
FLUSH PRIVILEGES;
如果使用 socket 连接,则账号 host 应该是 localhost:
CREATE USER IF NOT EXISTS 'mysqld_exporter'@'localhost' IDENTIFIED BY '<password>' WITH MAX_USER_CONNECTIONS 3;
GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO 'mysqld_exporter'@'localhost';
FLUSH PRIVILEGES;
Ansible 会生成 /etc/mysqld_exporter/.my.cnf:
[client]
user="mysqld_exporter"
password="<password>"
host=127.0.0.1
port=3306
systemd 服务中通过 --config.my-cnf 指定配置文件:
[Service]
User=mysqld_exporter
Group=mysqld_exporter
Type=simple
ExecStart=/usr/local/bin/mysqld_exporter --config.my-cnf=/etc/mysqld_exporter/.my.cnf --web.listen-address=:9104 --collect.info_schema.processlist
Restart=always
RestartSec=5
安装时需要传入密码变量:
MYSQLD_EXPORTER_PASSWORD='<password>' ansible-playbook -i inventories/netbox.yml \
playbooks/02-vm-ops/monitoring/mysqld_exporter_install.yml \
--limit db_mysql:&env_dmztest
验证时要同时看两个指标:
systemctl status mysqld_exporter
curl -s http://127.0.0.1:9104/metrics | grep '^mysql_up '
这里要注意:up=1 只代表 Prometheus 能抓到 exporter HTTP 端口,mysql_up=1 才代表 exporter 成功连接 MySQL。
自动处理主机防火墙
这套 playbook 会自动识别目标机本地防火墙:
- 如果
firewalldactive,则写入 permanent 和 runtime 规则 - 如果
ufwactive,则执行ufw allow - 如果没有识别到活动防火墙,则记录为
inactive
以 node_exporter 为例,等价动作如下:
firewall-cmd --permanent --add-port=9100/tcp
firewall-cmd --add-port=9100/tcp
或者:
ufw allow 9100/tcp
为什么 firewalld 要同时写 permanent 和 runtime?因为有些主机 permanent 已经存在,但 runtime 未生效;直接 --add-port 可以立即生效,同时避免 firewall-cmd --reload 清掉其他服务的 runtime-only 规则。
主机防火墙放行不等于云安全组放行。Prometheus 所在 Kubernetes 节点仍然需要能访问外部主机的
9100、9256、9104端口。
生成 Prometheus External Targets
安装 exporter 只是第一步。要让 Prometheus 抓到这些主机,还需要生成 additional-scrape-configs.yaml 并更新 Kubernetes Secret。
模板核心逻辑如下:
- job_name: "node-exporter"
static_configs:
- targets:
- "10.0.1.11:9100"
labels:
exporter: "node"
group: "cloud"
env: "dmztest"
source: "external"
business: "example"
host: "vm-example-01"
- job_name: "process-exporter"
static_configs:
- targets:
- "10.0.1.11:9256"
labels:
exporter: "process"
group: "cloud"
env: "dmztest"
source: "external"
business: "example"
host: "vm-example-01"
- job_name: "mysqld-exporter"
static_configs:
- targets:
- "10.0.1.12:9104"
labels:
exporter: "mysqld"
group: "mysql"
env: "dmztest"
source: "external"
business: "example"
host: "mysql-example-01"
实际执行命令:
ansible-playbook -i inventories/netbox.yml \
playbooks/02-vm-ops/monitoring/update_prometheus_targets.yml
它会生成配置文件并更新 Kubernetes Secret:
kubectl --kubeconfig /data/kubeconfig/monitoring-ci.conf \
apply -f /tmp/additional-scrape-configs-secret.yaml
kubectl --kubeconfig /data/kubeconfig/monitoring-ci.conf \
-n monitoring rollout restart statefulset/prometheus-kube-prometheus-stack-prometheus
这里的设计重点是:update_prometheus_targets.yml 不 SSH 到目标主机,主要逻辑都在控制机本地执行。它只读取 Ansible inventory 和 NetBox 字段,然后生成 Prometheus 配置。
GitLab CI 手动触发流程
为了避免 push 代码后自动修改生产主机,所有 exporter 相关 job 都设计为手动触发。
推荐执行顺序:
node_exporter_plan
node_exporter_install
process_exporter_plan
process_exporter_install
mysqld_exporter_plan
mysqld_exporter_install
update_prometheus_targets
按环境灰度时,可以传:
NODE_EXPORTER_ENV=dmztest
PROCESS_EXPORTER_ENV=dmztest
MYSQLD_EXPORTER_ENV=dmztest
如果要精确控制 Ansible limit,可以传:
NODE_EXPORTER_LIMIT=env_dmztest
PROCESS_EXPORTER_LIMIT=env_dmztest
MYSQLD_EXPORTER_LIMIT=db_mysql:&env_dmztest
安装类 job 默认禁止空 limit 全量执行,除非显式设置:
NODE_EXPORTER_APPLY_ALL=true
这个保护非常重要,尤其是在主机数量较多或存在生产环境时,可以避免一次误触发影响全部机器。
验证 Prometheus 与 Grafana
Prometheus 中可以使用以下 PromQL 验证:
up{job="node-exporter", source="external"}
查看主机基础指标:
node_uname_info{job="node-exporter"}
node_cpu_seconds_total{job="node-exporter"}
node_memory_MemAvailable_bytes{job="node-exporter"}
查看 MySQL exporter:
up{job="mysqld-exporter", source="external"}
mysql_up{job="mysqld-exporter", source="external"}
mysql_global_status_uptime{job="mysqld-exporter", source="external"}
Grafana 侧可以复用 Node Exporter 默认看板,例如:
Node Exporter / Nodes
Node Exporter / USE Method / Node
MySQL 看板要注意指标名称,当前使用的是:
mysql_info_schema_processlist_threads
而不是旧的 mysql_info_schema_threads。
避雷指南
不要把 dmztest 填到 NODE_EXPORTER_LIMIT
NetBox 动态 inventory 中的环境组通常是 env_dmztest,不是裸的 dmztest。
正确写法:
NODE_EXPORTER_ENV=dmztest
或者:
NODE_EXPORTER_LIMIT=env_dmztest
*_ENV 会自动拼成 env_<环境>,*_LIMIT 则需要填写真实的 Ansible limit。
update_prometheus_targets 必须全量执行
不要这样执行:
ansible-playbook -i inventories/netbox.yml \
playbooks/02-vm-ops/monitoring/update_prometheus_targets.yml \
--limit env_dmztest
原因是 Prometheus 的 additional-scrape-configs Secret 是整体配置。如果按环境生成 targets,会用当前环境覆盖整个 Secret,导致其他环境的 targets 从 Prometheus 中消失。
安装 exporter 可以按环境灰度,刷新 Prometheus targets 必须全量执行。
up=1 不代表 MySQL 采集正常
常见现象:
up{job="mysqld-exporter", instance="10.0.1.12:9104"} == 1
mysql_up{job="mysqld-exporter", instance="10.0.1.12:9104"} == 0
这说明 Prometheus 能访问 mysqld_exporter,但 mysqld_exporter 没连上 MySQL。
排查方向:
cat /etc/mysqld_exporter/.my.cnf
mysql -h 127.0.0.1 -P 3306 -u mysqld_exporter -p
如果 .my.cnf 使用 host=127.0.0.1,MySQL 账号必须是 'mysqld_exporter'@'127.0.0.1'。如果使用 socket,则通常需要 'mysqld_exporter'@'localhost'。
Grafana 没图,不一定是 Dashboard 问题
如果下面这个 PromQL 有结果:
up{job="node-exporter", instance="10.0.1.11:9100"}
但下面这个没有结果:
node_uname_info{job="node-exporter", instance="10.0.1.11:9100"}
说明 Prometheus 可能只记录了 scrape 状态指标,没有真正抓到 node exporter 的业务指标。
可以先在 Prometheus 查实际抓到了哪些指标:
count by (__name__) ({job="node-exporter", instance="10.0.1.11:9100"})
再到目标主机本地确认:
curl -s http://127.0.0.1:9100/metrics | grep node_uname_info
如果本机有指标而 Prometheus 没有,优先检查云安全组、路由和主机防火墙。
不建议用 serial 做批次控制
这套 playbook 的报告是在 post_tasks 中通过 run_once + delegate_to: localhost 汇总所有主机结果。
如果设置 serial: 30,Ansible 会每 30 台执行一批,post_tasks 也会每批执行一次,最终可能出现:
- 报告被分批生成
- 同秒时间戳互相覆盖
- GitLab CI 只读取最后一份报告
- 前面批次的失败被漏掉
当前更稳妥的方式是:
并发由 ansible.cfg 的 forks 控制
批次由 NODE_EXPORTER_ENV 或 NODE_EXPORTER_LIMIT 控制
报告在单次 play 结束后统一汇总
总结
这套 exporter 批量安装方案的核心价值,不只是把二进制分发到多台主机,而是把 主机来源、安装过程、防火墙处理、Prometheus 接入、Grafana 验证和故障排查 串成了一条完整链路。
对于中小规模外部云主机监控接入,NetBox + Ansible + GitLab CI + Prometheus additional scrape configs 是一个很实用的组合。它既保留了手动触发的安全边界,又能把重复安装和 targets 维护自动化,后续扩展 Redis、Nginx、JVM 等 exporter 时,也可以复用同样的模式。