268 lines
6.5 KiB
Markdown
268 lines
6.5 KiB
Markdown
# Ansible与HashiCorp Vault集成指南
|
||
|
||
本文档介绍如何将Ansible与HashiCorp Vault集成，以安全地管理和使用敏感信息。
|
||
|
||
## 1. 安装必要的Python包
|
||
|
||
首先，需要安装Ansible的Vault集成包：
|
||
|
||
```bash
|
||
pip install hvac
|
||
```
|
||
|
||
## 2. 配置Ansible使用Vault
|
||
|
||
### 2.1 创建Vault连接配置
|
||
|
||
创建一个Vault连接配置文件 `vault_config.yml`：
|
||
|
||
```yaml
|
||
vault_addr: http://localhost:8200
|
||
vault_role_id: "your-approle-role-id"
|
||
vault_secret_id: "your-approle-secret-id"
|
||
```
|
||
|
||
### 2.2 创建Vault查询角色
|
||
|
||
在Vault中创建一个专用于Ansible的AppRole：
|
||
|
||
```bash
|
||
# 启用AppRole认证
|
||
vault auth enable approle
|
||
|
||
# 创建策略
|
||
cat > ansible-policy.hcl <<EOF
|
||
path "kv/data/ansible/*" {
|
||
capabilities = ["read"]
|
||
}
|
||
EOF
|
||
|
||
vault policy write ansible ansible-policy.hcl
|
||
|
||
# 创建AppRole
|
||
vault write auth/approle/role/ansible \
|
||
token_policies="ansible" \
|
||
token_ttl=1h \
|
||
token_max_ttl=4h
|
||
|
||
# 获取Role ID
|
||
vault read auth/approle/role/ansible/role-id
|
||
|
||
# 生成Secret ID
|
||
vault write -f auth/approle/role/ansible/secret-id
|
||
```
|
||
|
||
## 3. 在Ansible中使用Vault
|
||
|
||
### 3.1 使用lookup插件
|
||
|
||
在Ansible playbook中使用`hashi_vault`查找插件：
|
||
|
||
```yaml
|
||
---
|
||
- name: 使用HashiCorp Vault的示例
|
||
hosts: all
|
||
vars:
|
||
vault_addr: "http://localhost:8200"
|
||
role_id: "{{ lookup('file', '/path/to/role_id') }}"
|
||
secret_id: "{{ lookup('file', '/path/to/secret_id') }}"
|
||
|
||
# 从Vault获取数据库密码
|
||
db_password: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password auth_method=approle role_id=' + role_id + ' secret_id=' + secret_id + ' url=' + vault_addr) }}"
|
||
|
||
tasks:
|
||
- name: 配置数据库连接
|
||
template:
|
||
src: db_config.j2
|
||
dest: /etc/app/db_config.ini
|
||
```
|
||
|
||
### 3.2 使用环境变量
|
||
|
||
也可以通过环境变量设置Vault认证信息：
|
||
|
||
```yaml
|
||
---
|
||
- name: 使用环境变量的Vault示例
|
||
hosts: all
|
||
environment:
|
||
VAULT_ADDR: "http://localhost:8200"
|
||
VAULT_ROLE_ID: "{{ lookup('file', '/path/to/role_id') }}"
|
||
VAULT_SECRET_ID: "{{ lookup('file', '/path/to/secret_id') }}"
|
||
|
||
tasks:
|
||
- name: 从Vault获取密钥
|
||
set_fact:
|
||
api_key: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/api:key') }}"
|
||
```
|
||
|
||
## 4. 创建Vault密钥模块
|
||
|
||
创建一个自定义的Ansible角色，用于管理Vault中的密钥：
|
||
|
||
### 4.1 角色结构
|
||
|
||
```
|
||
roles/
|
||
└── vault_secrets/
|
||
├── defaults/
|
||
│ └── main.yml
|
||
├── tasks/
|
||
│ └── main.yml
|
||
└── vars/
|
||
└── main.yml
|
||
```
|
||
|
||
### 4.2 主任务文件
|
||
|
||
`roles/vault_secrets/tasks/main.yml`:
|
||
|
||
```yaml
|
||
---
|
||
- name: 确保Vault令牌有效
|
||
block:
|
||
- name: 获取Vault令牌
|
||
set_fact:
|
||
vault_token: "{{ lookup('hashi_vault', 'auth_method=approle role_id=' + vault_role_id + ' secret_id=' + vault_secret_id + ' url=' + vault_addr) }}"
|
||
no_log: true
|
||
rescue:
|
||
- name: Vault认证失败
|
||
fail:
|
||
msg: "无法从Vault获取有效令牌"
|
||
|
||
- name: 从Vault读取密钥
|
||
set_fact:
|
||
secrets: "{{ lookup('hashi_vault', 'secret=' + vault_path + ' token=' + vault_token + ' url=' + vault_addr) }}"
|
||
no_log: true
|
||
|
||
- name: 设置各个密钥变量
|
||
set_fact:
|
||
"{{ item.key }}": "{{ item.value }}"
|
||
with_dict: "{{ secrets.data.data }}"
|
||
no_log: true
|
||
```
|
||
|
||
## 5. 将现有Ansible Vault迁移到HashiCorp Vault
|
||
|
||
### 5.1 创建迁移脚本
|
||
|
||
创建一个脚本来自动迁移Ansible Vault内容到HashiCorp Vault：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# migrate_to_hashicorp_vault.sh
|
||
|
||
# 设置变量
|
||
ANSIBLE_VAULT_FILE=$1
|
||
VAULT_PATH=$2
|
||
VAULT_ADDR=${VAULT_ADDR:-"http://localhost:8200"}
|
||
|
||
# 检查参数
|
||
if [ -z "$ANSIBLE_VAULT_FILE" ] || [ -z "$VAULT_PATH" ]; then
|
||
echo "用法: $0 <ansible_vault_file> <vault_path>"
|
||
echo "示例: $0 group_vars/all/vault.yml kv/ansible/group_vars/all"
|
||
exit 1
|
||
fi
|
||
|
||
# 检查Vault登录状态
|
||
if ! vault token lookup >/dev/null 2>&1; then
|
||
echo "请先登录Vault: vault login <token>"
|
||
exit 1
|
||
fi
|
||
|
||
# 解密Ansible Vault文件
|
||
echo "解密Ansible Vault文件..."
|
||
TEMP_FILE=$(mktemp)
|
||
ansible-vault decrypt --output="$TEMP_FILE" "$ANSIBLE_VAULT_FILE"
|
||
|
||
# 将YAML转换为JSON并存储到HashiCorp Vault
|
||
echo "迁移密钥到HashiCorp Vault..."
|
||
python3 -c "
|
||
import yaml, json, sys, subprocess
|
||
with open('$TEMP_FILE', 'r') as f:
|
||
data = yaml.safe_load(f)
|
||
for key, value in data.items():
|
||
cmd = ['vault', 'kv', 'put', '$VAULT_PATH/' + key, 'value=' + json.dumps(value)]
|
||
subprocess.run(cmd)
|
||
"
|
||
|
||
# 清理临时文件
|
||
rm "$TEMP_FILE"
|
||
|
||
echo "迁移完成! 数据已存储在Vault路径: $VAULT_PATH/"
|
||
```
|
||
|
||
### 5.2 执行迁移
|
||
|
||
```bash
|
||
# 赋予脚本执行权限
|
||
chmod +x migrate_to_hashicorp_vault.sh
|
||
|
||
# 执行迁移
|
||
./migrate_to_hashicorp_vault.sh group_vars/all/vault.yml kv/ansible/group_vars/all
|
||
```
|
||
|
||
## 6. 更新Ansible配置
|
||
|
||
### 6.1 修改ansible.cfg
|
||
|
||
更新`ansible.cfg`文件，添加Vault相关配置：
|
||
|
||
```ini
|
||
[defaults]
|
||
vault_identity_list = dev@~/.ansible/vault_dev.txt, prod@~/.ansible/vault_prod.txt
|
||
|
||
[hashi_vault_collection]
|
||
url = http://localhost:8200
|
||
auth_method = approle
|
||
role_id = /path/to/role_id
|
||
secret_id = /path/to/secret_id
|
||
```
|
||
|
||
### 6.2 更新现有Playbook
|
||
|
||
将现有playbook中的Ansible Vault引用替换为HashiCorp Vault引用：
|
||
|
||
```yaml
|
||
# 旧方式
|
||
- name: 使用Ansible Vault变量
|
||
debug:
|
||
msg: "数据库密码: {{ vault_db_password }}"
|
||
|
||
# 新方式
|
||
- name: 使用HashiCorp Vault变量
|
||
debug:
|
||
msg: "数据库密码: {{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password') }}"
|
||
```
|
||
|
||
## 7. 最佳实践
|
||
|
||
1. **避免硬编码认证信息**：使用环境变量或外部文件存储Vault认证信息
|
||
2. **限制令牌权限**：为Ansible创建的Vault令牌仅授予必要的最小权限
|
||
3. **设置合理的TTL**：为Vault令牌设置合理的生命周期，避免长期有效的令牌
|
||
4. **使用no_log**：对包含敏感信息的任务使用`no_log: true`防止日志泄露
|
||
5. **定期轮换认证凭据**：定期轮换AppRole的Secret ID
|
||
6. **使用CI/CD集成**：在CI/CD流程中集成Vault认证，避免手动管理令牌
|
||
|
||
## 8. 故障排除
|
||
|
||
### 8.1 常见问题
|
||
|
||
1. **认证失败**：
|
||
- 检查Role ID和Secret ID是否正确
|
||
- 验证AppRole是否有正确的策略附加
|
||
|
||
2. **路径错误**：
|
||
- KV v2引擎需要在路径中包含`data`，例如`kv/data/path`而不是`kv/path`
|
||
|
||
3. **权限问题**：
|
||
- 确保AppRole有足够的权限访问请求的密钥
|
||
|
||
### 8.2 调试技巧
|
||
|
||
```yaml
|
||
- name: 调试Vault查询
|
||
debug:
|
||
msg: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password auth_method=approle role_id=' + role_id + ' secret_id=' + secret_id + ' url=' + vault_addr) }}"
|
||
vars:
|
||
ansible_hashi_vault_debug: true |