基础设施即代码 / 系统课时
使用 Ansible Vault 管理秘密
使用 Ansible Vault 管理秘密
本课把数据库密码、API 令牌等敏感变量从普通 YAML 中分离出来,用 Ansible Vault 加密保存,并建立本地执行与 CI/CD 中都能解密的方式。完成后,你可以把密文提交到仓库,同时让解密凭据独立于代码流转。
学习目标
- 使用
ansible-vault创建并识别加密变量文件。 - 在 Playbook 中引用 Vault 变量而不把明文写入任务文件。
- 使用 Vault ID 把解密凭据安全接入自动化执行环境。
分离可公开变量与秘密变量
Vault 解决的是静态敏感数据加密:仓库里保存密文,执行时再由 Ansible 在内存中解密。常见做法是把普通变量放在 group_vars/all/main.yml,把密码、令牌等放在单独的 group_vars/all/vault.yml,并用 vault_ 前缀标识其敏感来源。
例如,普通变量可以引用秘密变量,而无需知道秘密实际存放方式。
# group_vars/all/main.yml
db_host: db.internal.example
db_user: app
db_password: "{{ vault_db_password }}"这段配置的生效行为是:Playbook 读取 db_password 时会继续解析 vault_db_password;只有提供正确 Vault 解密凭据时,后者才能得到明文值。

创建并确认 Vault 文件
先让 ansible-vault create 直接创建加密文件,避免先落地一个长期存在的明文文件。
mkdir -p group_vars/all
ansible-vault create --vault-id dev@prompt group_vars/all/vault.yml预期结果:终端要求输入并确认 dev 的 Vault 密码,随后打开编辑器。写入下面的变量并保存退出后,命令正常返回,文件内容以 Vault 密文形式落盘。
vault_db_password: "<PASSWORD>"其中 <PASSWORD> 代表实际秘密值,不应原样出现在课程仓库或日志中。可以只查看文件头确认它已经加密,而不执行解密。
head -n 1 group_vars/all/vault.yml预期输出
$ANSIBLE_VAULT;1.2;AES256;dev1.2 格式会记录 Vault ID 标签 dev。后面的密文每次加密都可能不同,因此不要用密文正文做固定比对。
在 Playbook 中解密使用
Playbook 只引用变量,不需要加入任何解密逻辑。下面用断言验证秘密变量能被成功解析,同时不输出其实际值。
# verify-vault.yml
- name: Verify encrypted variable
hosts: localhost
gather_facts: false
tasks:
- name: Check that the secret was decrypted
ansible.builtin.assert:
that:
- vault_db_password | length > 0
quiet: true执行时提供同一个 Vault ID。
ansible-playbook -i localhost, -c local --vault-id dev@prompt verify-vault.yml预期输出的关键部分如下,实际任务时间可能不同。
TASK [Check that the secret was decrypted] *************************************
ok: [localhost]
PLAY RECAP *********************************************************************
localhost : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0如果密码错误,Ansible 会在读取加密数据阶段失败,而不是把错误密文当成普通变量继续执行。
接入自动化执行环境
自动化流水线不适合等待交互式密码输入。更稳妥的方式是让 CI 或秘密管理系统在运行时注入一个权限受控的密码文件,再把它作为 Vault ID 的来源。
ansible-playbook -i inventory.ini --vault-id prod@/run/secrets/ansible-vault-pass site.yml预期结果:当 /run/secrets/ansible-vault-pass 存在、权限允许当前 Runner 读取且密码正确时,标记为 prod 的 Vault 数据可被解密,Playbook 正常继续;实际任务输出由 site.yml 决定。
Vault 保护的是“仓库中的秘密”,不是所有运行时泄露风险。即使变量已加密,任务一旦把解密后的值传给 debug、命令行参数或第三方程序,仍可能泄露,因此还需要配合日志抑制、最小权限和定期轮换。