# AWS BYOC Region Control - Observability 部署脚本

## 项目概述

本项目是 TiDB Cloud 在 AWS BYOC (Bring Your Own Cloud) 环境中部署可观测性基础设施的自动化脚本集合。它用于在客户自己的 AWS 账号中创建、管理和销毁完整的可观测性技术栈。

## 目录结构

```
o11y/
├── basic/              # 基础设施组件部署脚本
│   ├── addon          # 云插件部署 (Ingress, ALB, ExternalDNS等)
│   ├── apigateway     # API Gateway 和 VPC Link 部署
│   ├── dms            # 监控告警和SNS配置
│   ├── iam            # IAM 角色和策略配置
│   ├── nodegroup      # EKS 节点组配置 (已禁用)
│   ├── validate       # CloudFormation 模板验证
│   ├── aws/           # AWS 资源模板
│   │   ├── cloudformation/  # CloudFormation 模板
│   │   ├── kubernetes/      # K8s 清单文件
│   │   └── policies/        # IAM 策略文件
│   └── charts/        # Helm Chart 配置
├── finalizers/        # 资源清理和销毁脚本
│   ├── basic/         # 基础设施清理脚本
│   ├── dataplane      # 数据平面清理
│   ├── infra          # 基础设施清理
│   └── ...            # 其他组件清理脚本
├── dataplane          # 部署数据平面 (VMCluster, Loki, Alertmanager)
├── infra              # 部署基础设施组件
├── regional-server    # 部署 Regional Server 和 Data Server
├── drhouse            # 部署诊断服务
├── register-loki-datasource  # 注册 Loki 数据源
├── register-region-global    # 注册区域全局配置
├── register-region-meta      # 注册区域元数据
├── register-region-runbooks  # 注册 Runbooks 配置
├── lib.sh             # 公共函数库
└── lifecycle.json     # S3 生命周期配置 (90天过期)
```

## 主要功能模块

### 1. 基础设施部署 (basic/)

#### 1.1 IAM 配置 (iam)
- 配置 OIDC 提供商用于 EKS 集群的 IRSA (IAM Roles for Service Accounts)
- 创建统一的 IAM 角色，用于所有可观测性组件
- 角色包括：Load Balancer Controller、ExternalDNS、Cluster Autoscaler、Regional Server、Loki、VMBackup、AlertManager、O11Y Backup

#### 1.2 云插件部署 (addon)
- 部署 AWS Load Balancer Controller
- 部署 ExternalDNS 用于 DNS 记录管理
- 部署 Ingress Nginx Controller (读/写分离)
- 部署 Cluster Autoscaler
- 创建 CloudFormation 栈：
  - **ingress.yaml**: ALB/NLB、ACM证书、WAF ACL
  - **vpc-endpoint-service.yaml**: VPC 端点服务配置
- 创建 S3 Gateway Endpoint 用于访问 S3
- 配置私有 DNS 记录

#### 1.3 API Gateway (apigateway)
- 创建 API Gateway VPC Link V2
- 创建 REST API Gateway，包含两个端点：
  - `/ds/{proxy+}` - 数据服务器代理
  - `/rs/{proxy+}` - 区域服务器代理
- 配置 AWS IAM 认证
- 通过 VPC Link 连接到内部 NLB/ALB

#### 1.4 监控告警 (dms)
- 配置 SNS Topic 访问策略
- 创建 CloudWatch Alarms：
  - **WatchdogDown**: 监控死信看门狗
  - **AlertmanagerClusterFailedToSendAlerts**: 监控 AlertManager 发送失败

### 2. 核心服务部署

#### 2.1 基础设施 (infra)
- 部署自监控技术栈：
  - Prometheus 自监控
  - AlertManager
  - EventRouter
  - Volume Autoscaler
  - Self-Vector (日志收集)
  - Victoria Metrics Operator
  - Cert Manager
- 创建备份 S3 存储桶
- 获取 Clinic 凭证用于 AlertManager 认证

#### 2.2 数据平面 (dataplane)
- 部署 Victoria Metrics Cluster：
  - vmstorage (存储节点)
  - vmselect (查询节点)
  - vminsert (写入节点)
- 部署 Loki (日志存储)：
  - loki-ha-write
  - loki-ha-read
- 部署 AlertManager
- 创建 S3 存储桶：
  - vmclusterBucketName: `o11y-{env}-shared-{region}`
  - lokiBucketName: `loki-{env}-{region}-o11y` (90天生命周期策略)
- 配置 Nginx Ingress 类 (读/写分离)

#### 2.3 Regional Server (regional-server)
- 部署 Regional Server 和 Data Server
- 配置 VPC Endpoint Service
- 设置 WAF 和证书
- 创建诊断存储桶
- 配置跨账号访问角色

#### 2.4 DrHouse (drhouse)
- 部署诊断查询服务 (diagnosis-query)

### 3. 全局配置注册

#### 3.1 注册区域全局配置 (register-region-global)
- 获取 API Gateway 端点
- 向 tidbcloud/observability 仓库注册新区域
- 触发 Global Server CD 部署
- 触发 Global Infra CD 部署

#### 3.2 注册区域元数据 (register-region-meta)
- 向 observability 仓库注册区域元数据

#### 3.3 注册 Loki 数据源 (register-loki-datasource)
- 向 app-delivery 仓库注册 Loki 数据源
- 数据源名称: `Loki-{vendor}-{region}`
- URL: `https://{domain}/loki/self-monitoring`

#### 3.4 注册 Runbooks (register-region-runbooks)
- 向 runbooks 仓库注册新区域

### 4. 资源清理 (finalizers/)

所有 finalizer 脚本遵循相同的模式：
1. 从 S3 下载配置文件
2. 检查 EKS 集群是否存在
3. 如果集群已删除，跳过清理
4. 触发 GitHub Workflow 创建销毁 PR
5. 等待 PR 合并

#### 4.1 基础设施清理 (finalizers/basic/)
- **addon**: 删除 CloudFormation 栈 (ingress, vpc-endpoint-service)、删除 K8s 资源、删除 S3 Gateway Endpoint
- **iam**: 从 IAM 角色中移除 OIDC 信任关系
- **dms**: 删除 CloudWatch Alarms、清理 SNS 策略

## 公共函数库 (lib.sh)

### 主要函数

1. **wait_workflow_success(workflow, repo, interval)**
   - 等待 GitHub workflow 运行完成
   - 检查运行状态

2. **wait_workflow_run_to_merge(workflow, repo, timeout, interval)**
   - 等待 workflow 运行完成
   - 从日志中提取 PR 编号
   - 等待 PR 合并 (默认超时 3 分钟)

3. **wait_for_services_ready(services, timeout, interval)**
   - 等待 K8s 服务就绪
   - 检查 readyReplicas 状态
   - 默认超时 10 分钟

4. **eks_exists(cluster_name, region, profile)**
   - 检查 EKS 集群是否存在 (仅用于 finalizers)

5. **setup_o11y_deploy_profile(role_arn)**
   - 配置 AWS profile 用于跨账号部署

## 工作流程

### 创建流程

1. **IAM 配置** (o11y-basic-iam)
   - 配置 OIDC 信任关系
   - 创建 IAM 角色

2. **云插件部署** (o11y-basic-addon)
   - 部署 Ingress、ALB Controller、ExternalDNS
   - 创建证书和 WAF
   - 配置 VPC Endpoint Service

3. **API Gateway** (o11y-basic-apigateway)
   - 创建 VPC Link
   - 配置 REST API

4. **监控告警** (o11y-basic-dms)
   - 配置 SNS 和 CloudWatch Alarms

5. **基础设施** (o11y-infra)
   - 部署自监控栈

6. **数据平面** (o11y-dataplane)
   - 部署 Victoria Metrics、Loki、AlertManager

7. **Regional Server** (o11y-regional-server)
   - 部署服务器组件

8. **DrHouse** (o11y-drhouse)
   - 部署诊断服务

9. **注册** (o11y-register-*)
   - 向各个系统注册新区域

### 销毁流程

执行顺序与创建相反，通过 finalizers/ 下的脚本完成：
1. 取消注册各个系统
2. 销毁服务组件
3. 清理基础设施
4. 删除云插件
5. 清理 IAM 配置

## 配置来源

所有脚本从 S3 下载配置文件 (`CONFIG_PATH` 环境变量)，包含：
- 区域信息 (region, name, env)
- 云提供商 (cloudProvider)
- EKS 集群信息 (从 o11y-eks job 输出)
- IAM 配置 (从 o11y-basic-iam job 输出)
- 自定义选项 (jobOptions.o11yRegion)

## 依赖项

- **AWS CLI**: 用于管理 AWS 资源
- **kubectl**: 用于管理 Kubernetes 资源
- **yq**: 用于解析 YAML 配置
- **jq**: 用于处理 JSON 数据
- **gh**: GitHub CLI，用于触发和管理 GitHub Workflows
- **git**: 版本控制

## 目标仓库

- **tidbcloud/observability**: 主要的配置仓库，存放区域配置
- **tidbcloud/app-delivery**: 应用交付配置
- **tidbcloud/runbooks**: Runbooks 配置

## 关键特性

1. **BYOC 支持**: 所有脚本支持 `byoc: true` 标志
2. **读/写分离**: Nginx Ingress 分离读写流量
3. **多环境支持**: 支持 prod、dev 等多种环境
4. **跨账号部署**: 使用 AWS profile 和 IAM 角色实现跨账号操作
5. **自动化 PR**: 通过 GitHub Workflows 自动创建和合并配置 PR
6. **服务就绪检查**: 等待所有关键服务就绪后才完成任务
7. **安全配置**: 
   - 强制 S3 存储桶使用 HTTPS
   - WAF 保护
   - IAM 认证的 API Gateway

## 存储桶命名规则

- VMCluster: `o11y-{env}-shared-{logical_region_name}`
- Loki: `loki-{env}-{logical_region_name}-o11y`
- 备份: `o11y-{env}-{logical_region_name}-backups`
- DS日志: `{cluster_name}-ds-logs`

## DNS 配置

### 生产环境
- 托管区域: `observability.tidbcloud.com`

### 非生产环境
- 托管区域: `observability-{env}.pingcap.cloud`

### 端点
- Regional Server: `www.rs.{region}.aws.{hosted_zone}`
- Data Server: `www.ds.{region}.aws.{hosted_zone}`
- Prometheus 端点: `prometheus-endpoint-{zone}.{hosted_zone}`

## 生命周期管理

Loki 存储桶配置了自动生命周期策略，90天后自动过期删除数据。