摘要 Excerpt:
本文介绍如何通过 Ansible + HashiCorp Vault + GitLab CI 实现 Linux 账号密码自动轮换。方案支持定时触发、按环境过滤、远端密码修改后校验、成功后写入 Vault,并生成审计报告。文章还重点记录了 Vault HTTPS 证书校验失败的排查过程和 VAULT_CACERT 的正确配置方式。
背景:为什么要做密码自动轮换
在传统运维场景中,Linux 服务器上的业务账号密码经常存在几个问题:
- 密码长期不变,安全风险越来越高。
- 手工修改密码容易遗漏主机。
- 修改后没有统一的记录和审计。
- 密码保存方式不规范,容易散落在文档、聊天记录或个人本地。
- 一旦批量修改失败,很难判断哪些主机成功、哪些主机失败。
这次要解决的是一个具体场景:批量轮换 Linux 主机上的 dev 账号密码,并将轮换成功后的密码托管到 HashiCorp Vault。
整体目标很明确:
每台主机单独生成随机密码,远端确认修改成功后,才把新密码写入 Vault。失败主机不更新 Vault,避免 Vault 中保存和真实服务器不一致的密码。
最终方案使用三部分组合完成:
Ansible:负责连接目标主机、修改 Linux 账号密码、读取/etc/shadow做结果校验。HashiCorp Vault:负责保存最终密码,作为统一的密码托管中心。GitLab CI:负责定时触发任务、传入 Vault 凭据、收集执行报告。
整体架构思路
这套方案不是简单地“生成密码然后写入 Vault”,而是强调一个关键原则:
先确认远端密码真的改成功,再写 Vault。
完整流程如下:
GitLab CI 定时触发
|
v
使用 AppRole 登录 Vault,获取短期 VAULT_TOKEN
|
v
执行 Ansible Playbook
|
v
检查目标主机是否存在 dev 账号
|
v
控制端生成随机密码和 SHA-512 shadow hash
|
v
Ansible user 模块修改远端密码
|
v
读取远端 /etc/shadow 校验 hash 是否一致
|
v
校验成功后写入 Vault KV v2
|
v
生成 JSON / Markdown 报告,上传 GitLab Artifact
这个流程最重要的设计点是:Vault 只保存已验证成功的密码。
如果主机不可达、账号不存在、远端密码修改失败、/etc/shadow 校验失败,或者 Vault 写入失败,都会在报告中记录状态,但不会把未确认的密码写入 Vault。
Vault 最小权限设计
Vault 中建议单独为自动化任务创建一个最小权限策略。这个任务只需要写入 dev 账号密码,不应该拥有 Vault 管理员权限。
策略示例:
cat > /tmp/ansible-dev-password-rotator.hcl <<'EOF'
path "secret/data/ansible/linux/accounts/dev/*" {
capabilities = ["create", "update"]
}
path "secret/metadata/ansible/linux/accounts/dev/*" {
capabilities = ["create", "update", "read", "list"]
}
EOF
vault policy write ansible-dev-password-rotator /tmp/ansible-dev-password-rotator.hcl
这里使用的是 Vault KV v2,因此真正写入数据的 API 路径是:
secret/data/ansible/linux/accounts/dev/<inventory_hostname>
而使用 Vault CLI 查看时路径是:
vault kv get secret/ansible/linux/accounts/dev/<inventory_hostname>
KV v2 的 API 路径和 CLI 路径不完全一样,这是很多人第一次接入 Vault 时容易踩坑的地方。
使用 AppRole 给 GitLab CI 授权
GitLab CI 不建议保存长期 Vault Token。更合适的方式是使用 Vault AppRole。
AppRole 的好处是:
- GitLab 保存的是
role_id和secret_id。 - 每次 CI job 开始时临时登录 Vault。
- 登录成功后拿到短期
VAULT_TOKEN。 - Ansible 后续使用这个短期 token 写入 Vault。
启用 AppRole:
vault auth enable approle
创建专用角色:
vault write auth/approle/role/ansible-dev-password-rotator \
token_policies="ansible-dev-password-rotator" \
token_ttl="1h" \
token_max_ttl="2h" \
secret_id_ttl="0" \
secret_id_num_uses="0"
获取 role_id:
vault read auth/approle/role/ansible-dev-password-rotator/role-id
创建 secret_id:
vault write -f auth/approle/role/ansible-dev-password-rotator/secret-id
secret_id 只会显示一次,拿到后应立即保存到 GitLab CI/CD Variables,不要写入代码仓库。
Ansible 默认变量
Playbook 中通过环境变量读取 Vault 配置。这样本地运行和 CI 运行可以共用同一套逻辑。
# playbooks/04-security-baseline/vars/defaults.yml
dev_password_user: dev
dev_password_length: 12
dev_password_report_dir: reports/security-baseline/dev-password-rotation
dev_password_vault_addr: "{{ lookup('ansible.builtin.env', 'VAULT_ADDR') }}"
dev_password_vault_token: "{{ lookup('ansible.builtin.env', 'VAULT_TOKEN') }}"
dev_password_vault_namespace: "{{ lookup('ansible.builtin.env', 'VAULT_NAMESPACE') }}"
dev_password_vault_validate_certs: >-
{{
(lookup('ansible.builtin.env', 'VAULT_SKIP_VERIFY') | lower)
not in ['1', 'true', 'yes']
}}
dev_password_vault_ca_path: "{{ lookup('ansible.builtin.env', 'VAULT_CACERT') }}"
dev_password_vault_kv_mount: secret
dev_password_vault_path_prefix: ansible/linux/accounts/dev
dev_password_no_log: true
这里有几个关键点:
dev_password_no_log: true用于避免 Ansible 输出明文密码、shadow hash 和 Vault token。VAULT_SKIP_VERIFY=true可临时关闭 Vault HTTPS 证书校验。VAULT_CACERT用于传入 Vault CA 证书路径,推荐在生产环境使用。dev_password_vault_path_prefix控制密码写入 Vault 的路径前缀。
Ansible 密码轮换核心逻辑
下面是单台主机的核心处理流程。
- name: Check dev account exists
ansible.builtin.command: "getent passwd {{ dev_password_user }}"
register: _dev_passwd
changed_when: false
failed_when: false
- name: Generate new dev password and hash on controller
ansible.builtin.set_fact:
_dev_password_plain: >-
{{
lookup(
'ansible.builtin.password',
'/dev/null length=' ~ dev_password_length ~ ' chars=ascii_letters,digits,punctuation'
)
}}
_dev_password_rotated_at: "{{ lookup('pipe', 'TZ=Asia/Shanghai date -Iseconds') }}"
no_log: "{{ dev_password_no_log }}"
when: _dev_passwd.rc == 0
- name: Build stable dev password hash
ansible.builtin.set_fact:
_dev_password_hash: "{{ _dev_password_plain | password_hash('sha512') }}"
no_log: "{{ dev_password_no_log }}"
when: _dev_passwd.rc == 0
- name: Update dev password on remote host
ansible.builtin.user:
name: "{{ dev_password_user }}"
password: "{{ _dev_password_hash }}"
update_password: always
password_lock: false
register: _dev_user_update
failed_when: false
no_log: "{{ dev_password_no_log }}"
when: _dev_passwd.rc == 0
这里没有直接把明文密码传给远端命令,而是在控制端生成 SHA-512 shadow hash,再通过 Ansible user 模块写入系统账号。
接着读取远端 /etc/shadow,确认写入后的 hash 和本次生成的 hash 是否一致。
- name: Read devshadow hash after password update
ansible.builtin.command: "getent shadow {{ dev_password_user }}"
register: _dev_shadow_after
changed_when: false
failed_when: false
no_log: "{{ dev_password_no_log }}"
when: _dev_passwd.rc == 0
- name: Decide whether remote password update is verified
ansible.builtin.set_fact:
_dev_password_verified: >-
{{
(_dev_passwd.rc == 0)
and (_dev_user_update is defined)
and not (_dev_user_update.failed | default(false))
and ((_dev_shadow_after.rc | default(1)) == 0)
and (((_dev_shadow_after.stdout | default('')).split(':')[1] | default('')) == _dev_password_hash)
}}
no_log: "{{ dev_password_no_log }}"
when: _dev_passwd.rc == 0
只有 _dev_password_verified 为 true,才允许写 Vault。
- name: Write verified dev password to Vault KV v2
ansible.builtin.uri:
url: >-
{{
dev_password_vault_addr | regex_replace('/+$', '')
}}/v1/{{ dev_password_vault_kv_mount }}/data/{{
dev_password_vault_path_prefix | regex_replace('^/+', '') | regex_replace('/+$', '')
}}/{{ inventory_hostname | urlencode }}
method: POST
headers: >-
{{
{'X-Vault-Token': dev_password_vault_token}
| combine(
(dev_password_vault_namespace | default('') | trim | length > 0)
| ternary({'X-Vault-Namespace': dev_password_vault_namespace}, {})
)
}}
body_format: json
body:
data:
username: "{{ dev_password_user }}"
password: "{{ _dev_password_plain }}"
host: "{{ inventory_hostname }}"
ansible_host: "{{ ansible_host | default('') }}"
environment: "{{ custom_fields.environment | default('') }}"
business_owner: "{{ custom_fields.business_owner | default('') }}"
rotated_at: "{{ _dev_password_rotated_at }}"
rotated_by: "ansible-deploy"
verification: "shadow_hash_match"
validate_certs: "{{ dev_password_vault_validate_certs }}"
ca_path: >-
{{
dev_password_vault_ca_path
if (dev_password_vault_ca_path | default('') | trim | length > 0)
else omit
}}
status_code:
- 200
- 204
register: _dev_vault_write
changed_when: "_dev_vault_write.status | default(0) in [200, 204]"
failed_when: false
delegate_to: localhost
become: false
no_log: "{{ dev_password_no_log }}"
when:
- _dev_passwd.rc == 0
- _dev_password_verified | default(false)
这段代码有两个细节很重要:
delegate_to: localhost:写 Vault 的动作在 Ansible 控制端执行,而不是在目标业务服务器上执行。ca_path和validate_certs:让 Ansible 写 Vault 时也支持自定义 CA 证书。
GitLab CI 定时执行任务
GitLab CI 中定义 rotate_dev_password job,负责完成三件事:
- 使用 AppRole 登录 Vault,换取短期
VAULT_TOKEN。 - 执行 Ansible Playbook。
- 检查报告结果,并上传 Artifact。
核心配置如下:
variables:
ANSIBLE_INVENTORY: "inventories/netbox.yml"
dev_PASSWORD_PLAYBOOK: "playbooks/04-security-baseline/rotate_dev_password.yml"
dev_PASSWORD_ENV: ""
dev_PASSWORD_LIMIT: ""
dev_PASSWORD_EXTRA_VARS: ""
dev_PASSWORD_ROTATE: "false"
VAULT_APPROLE_AUTH_PATH: "approle"
VAULT_SKIP_VERIFY: "false"
ANSIBLE_CONFIG: "$CI_PROJECT_DIR/ansible.cfg"
ANSIBLE_PRIVATE_KEY_FILE: "/root/.ssh/id_ed25519_ansible"
ANSIBLE_HOST_KEY_CHECKING: "False"
rotate_dev_password job:
rotate_dev_password:
stage: ops
needs: []
resource_group: dev-password-rotation
timeout: 2h
script:
- |
report_dir="reports/security-baseline/dev-password-rotation/gitlab-${CI_PIPELINE_ID}-${CI_JOB_ID}"
ansible_limit=""
mkdir -p ci_artifacts/dev-password-rotation
if [ -n "${dev_PASSWORD_LIMIT:-}" ]; then
ansible_limit="${dev_PASSWORD_LIMIT:-}"
elif [ -n "${dev_PASSWORD_ENV:-}" ]; then
ansible_limit="env_${dev_PASSWORD_ENV:-}"
fi
if [ -z "${VAULT_ADDR:-}" ]; then
echo "ERROR: VAULT_ADDR is required"
exit 1
fi
if [ -z "${VAULT_ROLE_ID:-}" ]; then
echo "ERROR: VAULT_ROLE_ID is required"
exit 1
fi
if [ -z "${VAULT_SECRET_ID:-}" ]; then
echo "ERROR: VAULT_SECRET_ID is required"
exit 1
fi
vault_headers=()
if [ -n "${VAULT_NAMESPACE:-}" ]; then
vault_headers+=(--header "X-Vault-Namespace: ${VAULT_NAMESPACE}")
fi
vault_curl_args=()
if [ "${VAULT_SKIP_VERIFY:-false}" = "true" ]; then
vault_curl_args+=(--insecure)
elif [ -n "${VAULT_CACERT:-}" ]; then
vault_curl_args+=(--cacert "$VAULT_CACERT")
fi
login_payload="$(python3 - <<'PY'
import json
import os
print(json.dumps({
"role_id": os.environ["VAULT_ROLE_ID"],
"secret_id": os.environ["VAULT_SECRET_ID"],
}))
PY
)"
login_resp="$(curl -sS --request POST \
"${vault_curl_args[@]}" \
"${vault_headers[@]}" \
--data "$login_payload" \
"${VAULT_ADDR%/}/v1/auth/${VAULT_APPROLE_AUTH_PATH:-approle}/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")"
cmd=(
ansible-playbook
-i "$ANSIBLE_INVENTORY"
"$dev_PASSWORD_PLAYBOOK"
-e "dev_password_report_dir=${report_dir}"
)
if [ -n "$ansible_limit" ]; then
cmd+=(--limit "$ansible_limit")
fi
if [ -n "$dev_PASSWORD_EXTRA_VARS" ]; then
cmd+=(--extra-vars "$dev_PASSWORD_EXTRA_VARS")
fi
echo "Running: ansible-playbook -i ${ANSIBLE_INVENTORY} ${dev_PASSWORD_PLAYBOOK}"
set +e
"${cmd[@]}"
playbook_rc=$?
set -e
if [ ! -d "$report_dir" ] || [ -z "$(ls -A "$report_dir" 2>/dev/null)" ]; then
echo "Report directory was not generated: $report_dir (ansible-playbook rc=${playbook_rc})"
exit "${playbook_rc:-1}"
fi
mkdir -p ci_artifacts/dev-password-rotation
cp -a "${report_dir}/." ci_artifacts/dev-password-rotation/
latest_json=""
for report_json in "$report_dir"/dev_password_rotation_*.json; do
latest_json="$report_json"
done
if [ -z "$latest_json" ]; then
echo "No JSON report found under $report_dir"
exit 1
fi
python3 - "$latest_json" <<'PY'
import json
import sys
report_path = sys.argv[1]
with open(report_path, "r", encoding="utf-8") as fh:
report = json.load(fh)
summary = report.get("summary", {})
total = int(summary.get("total", 0))
success = int(summary.get("success", 0))
failed = total - success
print(f"Password rotation summary: success={success} failed={failed} total={total}")
if failed:
sys.exit(1)
PY
if [ "$playbook_rc" -ne 0 ]; then
exit "$playbook_rc"
fi
artifacts:
name: "dev-password-rotation-${CI_PIPELINE_ID}-${CI_JOB_ID}"
when: always
expire_in: 30 days
paths:
- ci_artifacts/dev-password-rotation/
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule" && $dev_PASSWORD_ROTATE == "true"'
when: on_success
allow_failure: false
- if: '$CI_PIPELINE_SOURCE == "web"'
when: manual
allow_failure: false
- when: manual
allow_failure: false
这里使用 resource_group: dev-password-rotation 是为了避免多个密码轮换任务并发执行。密码轮换属于高风险操作,宁愿排队,也不要同时跑多个 job。
GitLab CI/CD Variables 配置
项目中需要配置以下变量:
| 变量 | 类型建议 | 说明 |
|---|---|---|
VAULT_ADDR | 普通变量 | Vault 地址,例如 https://vault.example.com:8200 |
VAULT_ROLE_ID | Protected | AppRole 的 role_id |
VAULT_SECRET_ID | Masked + Protected | AppRole 的 secret_id |
VAULT_APPROLE_AUTH_PATH | 普通变量,可选 | 默认是 approle |
VAULT_NAMESPACE | 普通变量,可选 | Vault Enterprise namespace |
VAULT_CACERT | File 类型 | Vault HTTPS CA 证书 |
VAULT_SKIP_VERIFY | 普通变量 | 临时跳过证书校验,生产不建议 |
dev_PASSWORD_ROTATE | Schedule 变量 | 设置为 true 才允许定时轮换 |
dev_PASSWORD_ENV | 可选 | 例如 dmztest,转换成 --limit env_dmztest |
dev_PASSWORD_LIMIT | 可选 | 直接传 Ansible limit,优先级更高 |
定时任务建议在 GitLab CI/CD -> Schedules 中配置,并在 Schedule 变量里设置:
dev_PASSWORD_ROTATE=true
如果只轮换某个环境:
dev_PASSWORD_ENV=dmztest
报告设计:不要输出明文密码
密码轮换完成后,会生成 JSON 和 Markdown 两份报告。
报告只记录:
- 主机名
- IP
- 环境
- 系统信息
- Vault 路径
- 轮换时间
- 执行状态
- 错误原因
不会记录:
- 明文密码
- shadow hash
- Vault token
Markdown 报告模板示例:
# dev 密码轮换报告
- **生成时间**:{{ report_generated_at }}
- **目标范围**:{{ dev_password_summary.total }} 台(`protocol_ssh`)
- **Vault KV v2 路径前缀**:`{{ dev_password_summary.vault_mount }}/data/{{ dev_password_summary.vault_path_prefix }}`
- **说明**:报告不包含明文密码;成功主机的密码已写入 Vault。
## 汇总
| 状态 | 数量 |
|------|------|
| 成功,已写入 Vault (success) | {{ dev_password_summary.success }} |
| dev 账号不存在 (account_missing) | {{ dev_password_summary.account_missing }} |
| 远端修改失败 (change_failed) | {{ dev_password_summary.change_failed }} |
| 远端确认失败,未写 Vault (verify_failed) | {{ dev_password_summary.verify_failed }} |
| Vault 写入失败 (vault_failed) | {{ dev_password_summary.vault_failed }} |
| 不可达 (unreachable) | {{ dev_password_summary.unreachable }} |
| **合计** | **{{ dev_password_summary.total }}** |
这种报告适合直接作为 GitLab Artifact 保存,方便后续审计和问题追踪。
报告示例:

踩坑一:curl SSL certificate problem
实际运行时遇到过这个错误:
curl: (60) SSL certificate problem: unable to get local issuer certificate
这个错误发生在 GitLab CI 执行 AppRole 登录时:
curl -sS --request POST \
--data "$login_payload" \
"${VAULT_ADDR%/}/v1/auth/${VAULT_APPROLE_AUTH_PATH:-approle}/login"
它的意思是:GitLab Runner 不信任 Vault HTTPS 证书链。
Vault 服务器上通常会有类似文件:
/data/vault/tls/ca.crt
/data/vault/tls/vault.crt
/data/vault/tls/vault.key
/data/vault/pki/vault-ca.crt
/data/vault/pki/vault-ca.key
这些文件的作用不同:
| 文件 | 作用 | 是否可以放进 GitLab |
|---|---|---|
ca.crt 或 vault-ca.crt | CA 证书,用于客户端信任 Vault | 可以 |
vault.crt | Vault 服务端证书 | 不推荐作为 VAULT_CACERT |
vault.key | Vault 服务端私钥 | 绝对不可以 |
vault-ca.key | CA 私钥 | 绝对不可以 |
正确做法是在 GitLab 项目 Settings -> CI/CD -> Variables 添加:
Key: VAULT_CACERT
Type: File
Value: 粘贴 /data/vault/tls/ca.crt 的完整内容
证书内容类似:
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
GitLab 的 File 类型变量有一个特点:它不会把变量值直接作为字符串注入,而是在 job 运行时生成一个临时文件,然后让 VAULT_CACERT 指向这个文件路径。
所以脚本中可以这样使用:
curl --cacert "$VAULT_CACERT" ...
VAULT_CACERT解决的是“Runner 如何信任 Vault HTTPS 证书”的问题。它不是 Vault 权限凭据,也不会泄露 Vault 私钥。
踩坑二:临时跳过证书校验可以,但不要长期使用
脚本中支持:
VAULT_SKIP_VERIFY=true
开启后,CI 登录 Vault 时会使用:
curl --insecure ...
Ansible 写 Vault 阶段也会关闭证书校验。
这个方式适合临时排查问题,但不建议长期使用。因为它绕过了 HTTPS 证书校验,无法确认当前连接的 Vault 服务是否真的是预期目标。
生产环境推荐使用 VAULT_CACERT。
踩坑三:不要把密码写入 Vault 后才校验
一个容易犯的错误是:
生成密码 -> 写 Vault -> 改远端密码
或者:
生成密码 -> 改远端密码 -> 不校验直接写 Vault
这两种方式都有风险。
如果远端密码修改失败,但 Vault 已经保存了新密码,就会出现 Vault 中的密码和服务器真实密码不一致的问题。后续运维人员按 Vault 密码登录,会发现根本无法使用。
更稳妥的顺序应该是:
生成密码 -> 修改远端 -> 读取 /etc/shadow 校验 -> 成功后写 Vault
这也是本方案最核心的安全逻辑。
踩坑四:GitLab Artifact 上传成功不代表任务成功
这次排错时还有一个容易误判的点:job 失败后仍然上传了 artifact。
日志中可以看到:
Uploading artifacts...
ci_artifacts/dev-password-rotation/: found 1 matching artifact files and directories
Uploading artifacts as "archive" to coordinator... 201 Created
这并不表示密码轮换成功。
原因是 CI 脚本开头创建了 artifact 目录:
mkdir -p ci_artifacts/dev-password-rotation
即使后续 Vault 登录失败,GitLab 也能上传这个空目录或已有目录。
判断任务是否成功,要看:
- job 最终 exit code
Password rotation summary- JSON 报告中的
summary - Markdown 报告中的失败主机列表
总结
通过 Ansible + HashiCorp Vault + GitLab CI,可以把 Linux 账号密码轮换从手工操作升级为可审计、可定时、可回滚排查的自动化流程。
这套方案的关键优势是:
- GitLab CI 负责任务编排和定时触发。
- Vault AppRole 提供短期 token,避免长期 token 泄露风险。
- Ansible 逐台修改密码,并用
/etc/shadow做结果确认。 - 只有确认成功的主机才写入 Vault,避免密码托管数据失真。
- 报告不包含明文密码,但保留足够的审计信息。
VAULT_CACERT解决内网 Vault 自签名证书的可信问题。
最终落地时,最重要的不是“能不能批量改密码”,而是这条原则:
密码轮换任务必须以远端真实状态为准。只有服务器确认修改成功,Vault 才能保存新密码。