摘要(Excerpt)
本文记录一次数据库巡检自动化实战:使用 NetBox 管理资产和数据库字段,Ansible 执行 MySQL 只读巡检,GitLab CI 负责任务触发和报告归档,Vault Database Secrets Engine 动态下发临时数据库账号。文章重点介绍整体架构、关键代码、Vault 授权模型、GitLab CI 集成,以及真实排错过程中踩到的变量优先级、权限 403、客户端路径等问题。
背景:数据库巡检最怕两件事
在日常运维里,数据库巡检听起来不复杂,无非是查版本、连接数、慢查询、业务库容量、运行时长等指标。但真正落地到生产环境,会马上遇到几个现实问题。
第一,数据库主机不一定都在同一个环境,资产信息散落在 CMDB、Excel 或人工记录里。哪些主机是 MySQL,哪个端口,是否走 socket,谁来维护这些信息,都容易变成隐患。
第二,巡检账号怎么管。很多团队一开始会把 MySQL 账号密码写到 Ansible Vault、CI 变量甚至脚本里。短期看能跑,长期看就会遇到密码轮换困难、权限过大、泄露后难追踪的问题。
第三,巡检要能被审计。谁触发的,跑了哪些主机,哪些成功、哪些失败,报告在哪里留档,这些都需要形成闭环。
这次实践的目标就是把这几件事串起来:
用
NetBox管资产,用GitLab CI做调度入口,用Vault动态下发数据库只读账号,用Ansible执行巡检并生成报告。
最终链路如下:
NetBox 标记 MySQL 主机
-> Ansible inventory 生成 db_mysql 分组和变量
-> GitLab CI 用 DB_INSPECT_VAULT_* 登录 Vault
-> Vault 返回短期 VAULT_TOKEN
-> Ansible 用 VAULT_TOKEN 读取 database/creds/<vault_database_role>
-> Vault 创建动态只读 MySQL 账号
-> Ansible 在目标主机本地执行 mysql 巡检 SQL
-> 删除临时配置文件
-> 吊销 Vault lease
-> 汇总 JSON/Markdown 报告
-> GitLab artifact 留档
总体架构设计
这套方案拆成四层。
资产层:NetBox
NetBox 负责维护哪些主机是数据库主机,以及数据库相关元数据,例如 database_engine、database_port、database_socket、vault_database_role。Ansible 不再靠人工维护一份单独的数据库主机清单。
执行层:Ansible
Ansible 负责登录目标主机,在目标主机本地执行 mysql 客户端命令。这里的本地是指 MySQL 主机自己,所以报告里看到 127.0.0.1:3306 是正常的,它表示 Ansible SSH 到数据库主机后,在那台机器上连接本机 MySQL。
凭据层:Vault
Vault Database Secrets Engine 保存每台数据库的管理连接配置,并在巡检时动态创建临时只读账号。Ansible 不保存 MySQL 固定密码,也不在报告里输出动态密码。
调度与归档层:GitLab CI
GitLab CI 负责触发任务、用 AppRole 登录 Vault、运行 playbook,并把 JSON 和 Markdown 报告作为 artifact 保存。
NetBox:用字段驱动数据库分组
首先在 NetBox 里定义数据库相关字段。最终需要的字段如下:
database_engine:数据库类型,例如mysql,为空表示非数据库主机。database_port:MySQL 端口,例如3306。database_socket:本机 socket 路径,不填则走 TCP。vault_database_role:Vault Database Secrets Engine 的动态账号 role。
Ansible 的 NetBox 动态 inventory 中,通过 compose 把这些字段转成主机变量,通过 keyed_groups 自动生成数据库分组。
plugin: netbox.netbox.nb_inventory
validate_certs: false
config_context: false
interfaces: true
fetch_all: true
query_filters:
- status: active
compose:
ansible_host: primary_ip4.address.split('/')[0]
ansible_connection: "'winrm' if custom_fields.login_protocol == 'winrm' else 'ssh'"
login_protocol: custom_fields.login_protocol
maintenance_window: custom_fields.maintenance_window
database_engine: custom_fields.database_engine | default('', true)
db_inspect_mysql_port: custom_fields.database_port | default(3306, true)
db_inspect_mysql_socket: custom_fields.database_socket | default('', true)
db_inspect_vault_role: custom_fields.vault_database_role | default('mysql-readonly', true)
allow_auto_password_change: custom_fields.allow_auto_password_change
allow_auto_file_upload: custom_fields.allow_auto_file_upload
allow_auto_remediation: custom_fields.allow_auto_remediation
keyed_groups:
- key: custom_fields.environment
prefix: env
- key: platform.name
prefix: os
- key: custom_fields.business_owner
prefix: biz
- key: custom_fields.login_protocol
prefix: protocol
- key: custom_fields.database_engine | lower
prefix: db
这段配置的关键点是:database_engine=mysql 的主机会自动进入 db_mysql 分组。后续 MySQL 巡检 playbook 默认只跑这个组。
变量优先级:一个很容易踩的坑
最初实现时,我把 db_inspect_vault_role: mysql-readonly、db_inspect_mysql_command: mysql 这类默认值放在了 playbook 的 vars/defaults.yml,再通过 vars_files 加载。
这看起来像“默认变量”,但在 Ansible 里并不是低优先级默认值。vars_files 的优先级高于 inventory 变量,会覆盖 NetBox 动态 inventory 和 host_vars 下发的值。
实际表现就是:
- NetBox 明明下发了
db_inspect_vault_role=mysql-10-8-4-15-readonly。 - Playbook 实际却使用
mysql-readonly。 - Vault policy 只授权了
database/creds/mysql-10-8-4-15-readonly。 - 最终报
403 permission denied。
最终修正方式是:把“按主机可覆盖”的默认值放到 inventory 的 group_vars/db_mysql.yml,而不是 playbook 的 vars_files。
# db_mysql 组默认变量(仅作用于 NetBox database_engine=mysql 生成的 db_mysql 组)。
#
# 这些是“按主机可覆盖”的默认值,放在 inventory group_vars,优先级低于:
# - NetBox 动态 inventory 下发的 host 变量(custom_fields.* compose)
# - inventories/host_vars/<host>.yml
# 因此 NetBox 字段或 host_vars 一旦设置,会自动覆盖这里的默认值。
#
# 注意:不要把这些变量放进 playbooks/05-db-ops/vars/defaults.yml,
# 因为 play 的 vars_files 优先级高于 inventory,会反过来覆盖 NetBox / host_vars。
db_inspect_mysql_host: "127.0.0.1"
db_inspect_mysql_port: 3306
db_inspect_mysql_socket: ""
db_inspect_mysql_command: mysql
db_inspect_vault_role: mysql-readonly
这次排错最大的经验是:不要把“希望被 inventory 覆盖的默认值”放进
vars_files。它不是低优先级默认值,而是会压过 inventory 的 play 变量。
Vault:用动态账号代替固定密码
Vault Database Secrets Engine 的核心是两类对象:database/config/<name> 和 database/roles/<role>。
database/config/<name> 定义 Vault 如何连接数据库,里面保存管理账号和连接地址。database/roles/<role> 定义申请动态账号时执行什么 SQL,以及账号 TTL。
单实例示例:
export VAULT_ADDR='https://vault.example.com:8200'
export VAULT_TOKEN='<admin-token>'
vault secrets enable database
vault write database/config/mysql-hcn \
plugin_name=mysql-database-plugin \
allowed_roles="mysql-readonly" \
connection_url="{{username}}:{{password}}@tcp(mysql-hcn-ip:3306)/" \
username="root" \
password="<root-password>"
vault write database/roles/mysql-readonly \
db_name=mysql-hcn \
creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT, PROCESS, SHOW DATABASES, REPLICATION CLIENT ON *.* TO '{{name}}'@'%';" \
default_ttl="30m" \
max_ttl="2h"
这里的 db_name=mysql-hcn 不是 MySQL 里的业务库名,而是 Vault 里的连接配置名,也就是 database/config/mysql-hcn。
如果每台 MySQL 的 root/admin 密码不同,建议每台 MySQL 建独立连接配置和只读 role。
vault write database/config/mysql-10-8-4-15 \
plugin_name=mysql-database-plugin \
allowed_roles="mysql-10-8-4-15-readonly" \
connection_url="{{username}}:{{password}}@tcp(10.8.4.15:3306)/" \
username="vault_admin" \
password="<10.8.4.15-vault-admin-password>"
vault write database/roles/mysql-10-8-4-15-readonly \
db_name=mysql-10-8-4-15 \
creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT, PROCESS, SHOW DATABASES, REPLICATION CLIENT ON *.* TO '{{name}}'@'%';" \
default_ttl="30m" \
max_ttl="2h"
NetBox 中对应主机填写:
vault_database_role: mysql-10-8-4-15-readonly
这样 Ansible 会请求:
GET /v1/database/creds/mysql-10-8-4-15-readonly
Vault 创建临时 MySQL 用户并返回 username、password 和 lease_id。
Vault AppRole:CI 只拿最小权限
数据库巡检使用独立的 AppRole,例如 ansible-db-inspector,不要复用其他运维任务的 AppRole。
Policy 示例:
# 单实例或默认 role。
path "database/creds/mysql-readonly" {
capabilities = ["read"]
}
# 多 MySQL 实例独立 role 时,可按命名规范授权全部 mysql-* 动态账号 role。
path "database/creds/mysql-*" {
capabilities = ["read"]
}
# 后续扩展 Oracle、PostgreSQL 时,也可以继续追加对应 role。
path "database/creds/oracle-readonly" {
capabilities = ["read"]
}
path "sys/leases/revoke" {
capabilities = ["update"]
}
写入 policy 并创建 AppRole:
vault policy write ansible-db-inspector /tmp/ansible-db-inspector.hcl
vault write auth/approle/role/ansible-db-inspector \
token_policies="ansible-db-inspector" \
token_ttl="1h" \
token_max_ttl="2h" \
secret_id_ttl="0" \
secret_id_num_uses="0"
获取 role_id 和 secret_id 后,保存到 GitLab CI/CD Variables:
vault read auth/approle/role/ansible-db-inspector/role-id
vault write -f auth/approle/role/ansible-db-inspector/secret-id
GitLab 变量建议如下:
VAULT_ADDR:Vault 地址。DB_INSPECT_VAULT_ROLE_ID:数据库巡检 AppRole 的 role_id。DB_INSPECT_VAULT_SECRET_ID:数据库巡检 AppRole 的 secret_id。DB_INSPECT_VAULT_APPROLE_AUTH_PATH:可选,数据库巡检专用 AppRole mount。VAULT_CACERT或VAULT_SKIP_VERIFY:Vault HTTPS 证书配置。
GitLab CI:先换 Token,再跑 Ansible
GitLab CI job 的关键逻辑是:用 DB_INSPECT_VAULT_ROLE_ID 和 DB_INSPECT_VAULT_SECRET_ID 登录 Vault,换取短期 VAULT_TOKEN,再启动 ansible-playbook。
mysql_db_inspection:
stage: inspect
needs: []
resource_group: mysql-db-inspection
timeout: 2h
script:
- |
report_dir="reports/db-ops/mysql-inspection/gitlab-${CI_PIPELINE_ID}-${CI_JOB_ID}"
ansible_limit=""
mkdir -p ci_artifacts/mysql-inspection
if [ -z "${VAULT_ADDR:-}" ]; then
echo "ERROR: VAULT_ADDR is required"
exit 1
fi
if [ -z "${DB_INSPECT_VAULT_ROLE_ID:-}" ]; then
echo "ERROR: DB_INSPECT_VAULT_ROLE_ID is required"
exit 1
fi
if [ -z "${DB_INSPECT_VAULT_SECRET_ID:-}" ]; then
echo "ERROR: DB_INSPECT_VAULT_SECRET_ID is required"
exit 1
fi
db_inspect_vault_approle_auth_path="${DB_INSPECT_VAULT_APPROLE_AUTH_PATH:-${VAULT_APPROLE_AUTH_PATH:-approle}}"
login_payload="$(python3 - <<'PY'
import json
import os
print(json.dumps({
"role_id": os.environ["DB_INSPECT_VAULT_ROLE_ID"],
"secret_id": os.environ["DB_INSPECT_VAULT_SECRET_ID"],
}))
PY
)"
login_resp="$(curl -sS --request POST \
--data "$login_payload" \
"${VAULT_ADDR%/}/v1/auth/${db_inspect_vault_approle_auth_path}/login")"
export VAULT_TOKEN="$(python3 -c '
import json
import sys
resp = json.load(sys.stdin)
errors = resp.get("errors")
if errors:
raise SystemExit("Vault AppRole login failed: " + "; ".join(map(str, errors)))
token = resp.get("auth", {}).get("client_token")
if not token:
raise SystemExit("Vault AppRole login response did not contain auth.client_token")
print(token)
' <<< "$login_resp")"
ansible-playbook -i "$ANSIBLE_INVENTORY" "$DB_INSPECT_PLAYBOOK" \
-e "db_inspect_report_dir=${report_dir}"
artifacts:
name: "mysql-inspection-${CI_PIPELINE_ID}-${CI_JOB_ID}"
when: always
expire_in: 30 days
paths:
- ci_artifacts/mysql-inspection/
实际项目里还包含 limit、extra vars、报告复制和 JSON 汇总判断。核心思想不变:CI 只负责换取短期 Vault token,真正数据库密码由 Vault 动态生成。
Ansible Playbook:只跑 db_mysql 分组
主 playbook 默认只巡检 db_mysql:
- name: MySQL database inspection with Vault dynamic credentials
hosts: "{{ db_inspect_hosts | default('db_mysql') }}"
gather_facts: true
become: false
ignore_unreachable: true
any_errors_fatal: false
max_fail_percentage: 100
vars_files:
- vars/defaults.yml
pre_tasks:
- name: Skip hosts not marked as MySQL database in NetBox
ansible.builtin.meta: end_host
vars:
_db_engine: "{{ database_engine | default(custom_fields.database_engine | default('')) | lower }}"
when: _db_engine not in (db_inspect_database_engines | map('lower') | list)
tasks:
- name: Run MySQL inspection
ansible.builtin.include_tasks: tasks/mysql_inspection.yml
这里有两层保护:第一层是 inventory 自动生成 db_mysql 分组,第二层是 playbook 再检查 database_engine。即使有人手工扩大了 hosts,非 MySQL 主机也会被跳过。
申请动态账号并执行巡检
Ansible 使用 uri 模块调用 Vault API:
- name: Request dynamic MySQL credentials from Vault
ansible.builtin.uri:
url: >-
{{
db_inspect_vault_addr | regex_replace('/+$', '')
}}/v1/{{ db_inspect_vault_database_mount | regex_replace('^/+', '') | regex_replace('/+$', '') }}/creds/{{
db_inspect_vault_role | urlencode
}}
method: GET
headers: >-
{{
{'X-Vault-Token': db_inspect_vault_token}
| combine(
(db_inspect_vault_namespace | default('') | trim | length > 0)
| ternary({'X-Vault-Namespace': db_inspect_vault_namespace}, {})
)
}}
status_code:
- 200
register: _db_vault_creds
changed_when: false
failed_when: false
delegate_to: localhost
become: false
no_log: "{{ db_inspect_no_log }}"
拿到账号后,在目标主机写入临时 MySQL option file:
- name: Write temporary MySQL option file
ansible.builtin.copy:
dest: "{{ _db_mysql_defaults_file.path }}"
mode: "0600"
content: |
[client]
user={{ _db_vault_username }}
password={{ _db_vault_password }}
no_log: "{{ db_inspect_no_log }}"
when: _db_mysql_defaults_file.path is defined
执行 SQL 时不把密码放在命令行参数里,而是通过 --defaults-extra-file 读取:
- name: Execute MySQL inspection queries
ansible.builtin.command:
argv: "{{ _db_inspect_mysql_argv + ['--execute', item.sql] }}"
loop: "{{ db_inspect_queries }}"
loop_control:
label: "{{ item.name }}"
register: _db_query_exec
changed_when: false
failed_when: false
when: _db_inspect_mysql_argv is defined
巡检 SQL 包括:
SELECT VERSION();SELECT @@hostname;SHOW VARIABLES LIKE 'max_connections';SHOW GLOBAL STATUS LIKE 'Threads_connected';SHOW GLOBAL STATUS LIKE 'Threads_running';SHOW GLOBAL STATUS LIKE 'Slow_queries';- 查询业务库数量和最大库容量。
临时账号如何回收
Vault 返回动态账号时会带 lease_id。巡检结束后,Ansible 会调用:
PUT /v1/sys/leases/revoke
对应任务如下:
- name: Revoke Vault database credential lease
ansible.builtin.uri:
url: "{{ db_inspect_vault_addr | regex_replace('/+$', '') }}/v1/sys/leases/revoke"
method: PUT
headers: >-
{{
{'X-Vault-Token': db_inspect_vault_token}
}}
body_format: json
body:
lease_id: "{{ _db_vault_lease_id }}"
status_code:
- 200
- 204
register: _db_vault_revoke
changed_when: "_db_vault_revoke.status | default(0) in [200, 204]"
failed_when: false
delegate_to: localhost
become: false
no_log: "{{ db_inspect_no_log }}"
when:
- db_inspect_vault_revoke_lease | bool
- _db_vault_lease_id | default('') | trim | length > 0
正常情况下,巡检结束立即回收。即使 revoke 因异常没有执行成功,Vault 动态账号也会按 default_ttl 到期回收,例如 30m。
报告输出与 GitLab Artifact
巡检完成后,Ansible 会汇总每台主机的结果,生成 JSON 和 Markdown 两份报告。
reports/db-ops/mysql-inspection/mysql_inspection_<timestamp>.json
reports/db-ops/mysql-inspection/mysql_inspection_<timestamp>.md
在 GitLab CI 中,这些文件会复制到:
ci_artifacts/mysql-inspection/
如果报告里有 crit 或 unreachable,job 会失败。这样做的好处是:CI 状态可以直接提醒巡检异常,但报告仍然会作为 artifact 留下来,便于排查。
踩坑与避坑指南
坑一:Vault policy 正确,但 CI 仍然 403
表现:
status=403, errors=permission denied
排查思路:
vault read auth/approle/role/ansible-db-inspector
vault write auth/approle/login role_id='<role_id>' secret_id='<secret_id>'
VAULT_TOKEN='<client_token>' vault read database/creds/mysql-10-8-4-15-readonly
如果手工读成功,说明 Vault policy 和 role 本身没问题。此时要检查 GitLab CI 变量是否使用了正确的 DB_INSPECT_VAULT_ROLE_ID 和 DB_INSPECT_VAULT_SECRET_ID,以及 Ansible 实际请求的 db_inspect_vault_role 是否被变量优先级覆盖。
坑二:vars_files 覆盖了 NetBox 和 host_vars
这是本次最大的坑。vars_files 不是低优先级默认值,它的优先级会高于 inventory 变量。
错误做法是把这些变量放进 playbook 的 vars/defaults.yml:
db_inspect_mysql_command: mysql
db_inspect_vault_role: mysql-readonly
正确做法是放进 inventories/group_vars/db_mysql.yml,让 NetBox 和 host_vars 可以覆盖它们。
如果一个变量希望被 NetBox 或 host_vars 按主机覆盖,就不要放到 playbook 的
vars_files里。
坑三:目标主机能执行 mysql,Ansible 却找不到
在目标主机交互式登录时,mysql --version 正常。但 Ansible 非交互 SSH 可能不会加载完整 PATH。
例如目标机器实际路径是:
which mysql
/data/mysql/bin/mysql
这时可以在对应 host_vars 中指定绝对路径:
ansible_port: 22
db_inspect_mysql_command: /data/mysql/bin/mysql
坑四:报告里显示 127.0.0.1:3306,是不是连错了
不是连错。报告中的 127.0.0.1:3306 是 Ansible SSH 到目标 MySQL 主机后,在那台机器本地连接 MySQL。
Vault 创建动态账号时使用的是 database/config/<name> 里的连接地址,例如 10.8.4.15:3306。这两条链路不同:
Vault -> 10.8.4.15:3306 创建动态账号
Ansible -> SSH 到 10.8.4.15 -> 127.0.0.1:3306 执行巡检 SQL
坑五:SQL 没执行时不要误报 12 条 query failed
当 Vault 申请动态账号失败时,SQL 查询会被跳过。最初的处理逻辑把 skipped 也统计成 failed,导致报告里同时出现 Vault 失败和 12 条 SQL 失败,噪音很大。
最终处理方式是把 skipped 查询单独标记为 skipped,只在 SQL 真正执行且返回非 0 时统计为 failed。
适合扩展到 Oracle 和 PostgreSQL 吗
适合。设计时没有把 CI 变量命名成 MYSQL_*,而是使用通用的 DB_INSPECT_VAULT_*。
后续扩展 Oracle 时,可以继续复用:
DB_INSPECT_VAULT_ROLE_IDDB_INSPECT_VAULT_SECRET_IDDB_INSPECT_VAULT_APPROLE_AUTH_PATH
只需要增加新的 NetBox 字段值、Ansible playbook 和 Vault policy,例如:
path "database/creds/oracle-readonly" {
capabilities = ["read"]
}
资产分组也可以沿用 database_engine:
database_engine=oracle -> db_oracle
database_engine=mysql -> db_mysql
总结
这次实践的核心价值不是写了几个 SQL,而是把数据库巡检变成了一条可审计、可扩展、低凭据风险的自动化链路。
NetBox 负责资产与数据库元数据,GitLab CI 负责任务入口与报告归档,Vault 负责动态账号和最小权限授权,Ansible 负责真正执行巡检逻辑。
最终效果是:
- 不在仓库、CI 或 Ansible 变量里保存数据库固定密码。
- 每次巡检使用 Vault 动态只读账号。
- 巡检结束后自动吊销 lease,异常情况下也按 TTL 回收。
- 报告自动生成 JSON 和 Markdown,并通过 GitLab artifact 留档。
- 通过
database_engine和vault_database_role可以自然扩展到多实例、多数据库类型。
对运维自动化来说,这种设计比“写死账号密码跑脚本”多走了几步,但换来的是安全性、可维护性和审计能力的明显提升。