mgmt/docs/setup/consul-terraform-integration.md

Consul + Terraform 集成指南

本指南介绍如何使用 Consul 安全地管理 Terraform 中的敏感配置信息，特别是 Oracle Cloud 的凭据。

概述

我们使用 Consul 作为安全的密钥存储，避免在 Terraform 配置文件中直接暴露敏感信息。

架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Terraform     │───▶│     Consul      │───▶│  Oracle Cloud   │
│                 │    │   (密钥存储)     │    │                 │
│ consul provider │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

前提条件

1. Consul 集群正在运行
2. 可以访问 Consul API (默认: http://localhost:8500)
3. 已安装 curl 和 Terraform

快速开始

1. 启动 Consul 集群

# 进入 swarm 目录
cd swarm

# 启动 Consul 集群
docker-compose -f configs/traefik-consul-setup.yml up -d

2. 设置 Oracle Cloud 配置

# 使用密钥管理脚本设置配置
./scripts/utilities/consul-secrets-manager.sh set-oracle

脚本会提示你输入：

• 租户 OCID
• 用户 OCID
• API 密钥指纹
• 私钥文件路径
• 区间 OCID

3. 配置 Terraform

# 设置 Terraform Consul Provider
./scripts/utilities/terraform-consul-provider.sh setup

4. 验证配置

# 查看存储在 Consul 中的配置
./scripts/utilities/consul-secrets-manager.sh get-oracle

5. 运行 Terraform

cd infrastructure/environments/dev

# 初始化 Terraform
terraform init

# 规划部署
terraform plan

# 应用配置
terraform apply

详细说明

Consul 密钥存储结构

config/
└── dev/
    └── oracle/
        ├── tenancy_ocid
        ├── user_ocid
        ├── fingerprint
        ├── private_key
        └── compartment_ocid

脚本功能

consul-secrets-manager.sh

• set-oracle: 设置 Oracle Cloud 配置到 Consul
• get-oracle: 从 Consul 获取配置信息
• delete-oracle: 删除 Consul 中的配置
• generate-vars: 生成临时 Terraform 变量文件
• cleanup: 清理临时文件

terraform-consul-provider.sh

• setup: 创建 Terraform Consul Provider 配置文件

安全特性

1. 敏感信息隔离: 私钥等敏感信息只存储在 Consul 中
2. 临时文件: 私钥文件只在 Terraform 运行时临时创建
3. 权限控制: 临时私钥文件设置为 600 权限
4. 自动清理: 提供清理脚本删除临时文件

环境变量

# Consul 地址
export CONSUL_ADDR="http://localhost:8500"

# Consul ACL Token (如果启用了 ACL)
export CONSUL_TOKEN="your-token"

# 环境名称
export ENVIRONMENT="dev"

故障排除

Consul 连接问题

# 检查 Consul 状态
curl http://localhost:8500/v1/status/leader

# 检查 Consul 服务
docker ps | grep consul

配置验证

# 验证 Consul 中的配置
curl http://localhost:8500/v1/kv/config/dev/oracle?recurse

# 检查 Terraform 配置
terraform validate

清理和重置

# 清理临时文件
./scripts/utilities/consul-secrets-manager.sh cleanup

# 删除 Consul 中的配置
./scripts/utilities/consul-secrets-manager.sh delete-oracle

最佳实践

1. 定期轮换密钥: 定期更新 Oracle Cloud API 密钥
2. 备份配置: 定期备份 Consul 数据
3. 监控访问: 监控 Consul 密钥访问日志
4. 环境隔离: 不同环境使用不同的 Consul 路径

扩展其他云服务商

可以类似地为其他云服务商添加 Consul 集成：

# 华为云配置路径
config/dev/huawei/access_key
config/dev/huawei/secret_key

# AWS 配置路径  
config/dev/aws/access_key
config/dev/aws/secret_key

# Google Cloud 配置路径
config/dev/gcp/service_account_key

相关文件

• infrastructure/environments/dev/terraform.tfvars - Terraform 变量配置
• scripts/utilities/consul-secrets-manager.sh - Consul 密钥管理脚本
• scripts/utilities/terraform-consul-provider.sh - Terraform Consul Provider 配置脚本
• swarm/configs/traefik-consul-setup.yml - Consul 集群配置

支持

如有问题，请检查：

1. Consul 集群是否正常运行
2. 网络连接是否正常
3. 权限设置是否正确
4. 环境变量是否正确设置