# 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 集群

当前集群已从 Docker Swarm 迁移到 Nomad + Podman，请使用 Nomad 部署 Consul 集群：

```bash
nomad run /root/mgmt/consul-cluster-nomad.nomad
```

### 2. 设置 Oracle Cloud 配置

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

脚本会提示你输入：
- 租户 OCID
- 用户 OCID  
- API 密钥指纹
- 私钥文件路径
- 区间 OCID

### 3. 配置 Terraform

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

### 4. 验证配置

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

### 5. 运行 Terraform

```bash
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. **自动清理**: 提供清理脚本删除临时文件

## 环境变量

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

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

# 环境名称
export ENVIRONMENT="dev"
```

## 故障排除

### Consul 连接问题

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

# 检查 Consul 服务
docker ps | grep consul
```

### 配置验证

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

# 检查 Terraform 配置
terraform validate
```

### 清理和重置

```bash
# 清理临时文件
./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 集成：

```bash
# 华为云配置路径
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. 环境变量是否正确设置