📚 课程目录第4章集成架构总览

4. 集成架构总览：模板引擎与控制平面基线核验集成的高层架构图与数据流

本章从全局视角出发，定义模板引擎（Template Engine）与控制平面（Control Plane）基线核验（Baseline Verification）之间的集成架构。该架构遵循“声明式模板驱动、异步核验、状态回写”的核心原则，确保基础设施即代码（IaC）的变更在生效前经过严格的合规与安全基线校验。

4.1 高层架构图：分层与职责

集成架构分为四个逻辑层：用户接入层、模板编排层、控制平面层与目标集群层。每一层通过明确的 API 契约与事件总线进行通信，避免紧耦合。

  架构设计要点：
  模板引擎负责将用户输入的参数与预定义的 Helm/Kustomize 模板结合，生成待发布的 Kubernetes 资源清单。
控制平面作为核验中枢，接收资源清单后触发基线策略引擎（OPA/Gatekeeper）进行静态与动态校验。
核验结果通过异步回调或状态同步机制返回给模板引擎，决定是否继续执行部署。

4.2 核心数据流：从模板提交到核验闭环

数据流描述了用户提交参数化配置后，模板引擎与控制平面之间完整的交互过程。整个流程采用异步非阻塞设计，避免核验过程阻塞模板渲染管线。

步骤	发起方	接收方	数据内容	协议/方式
1. 提交参数	用户/GitOps	模板引擎	values.yaml, 环境标签, 版本号	HTTP REST / Git Push
2. 渲染模板	模板引擎	（内部）	生成完整 K8s 资源清单	内存处理
3. 提交核验	模板引擎	控制平面	资源清单 + 元数据（命名空间、集群ID）	gRPC / HTTP Webhook
4. 基线检查	控制平面	策略引擎	资源清单 → 策略规则匹配	内部调用
5. 返回结果	控制平面	模板引擎	通过/拒绝 + 违规详情 + 建议修复	异步回调 / 消息队列
6. 状态更新	模板引擎	用户/GitOps	核验状态、审批链接、部署阻断信息	Webhook / PR Comment

数据流设计要点：步骤 3 与步骤 5 之间采用消息队列（如 NATS / Kafka）解耦，确保控制平面在高并发核验请求下不会成为模板引擎的阻塞点。模板引擎在等待核验结果期间，可以继续处理其他渲染任务。

4.3 集成数据流时序图

下图以时序方式展示一次完整的基线核验集成交互过程，重点突出异步回调与状态同步机制。

4.4 关键集成接口与契约

模板引擎与控制平面之间的集成依赖以下核心接口。所有接口均需提供 OpenAPI / Protobuf 定义，确保双方团队可以并行开发与测试。

接口名称方向协议请求体示例响应体示例

接口名称	方向	协议	请求体示例	响应体示例
`SubmitVerification`	模板引擎 → 控制平面	gRPC	`{ "cluster_id": "prod-01", "namespace": "default", "resources": [ ... ], "template_meta": { "name": "my-app", "version": "1.2.3" } }`	`{ "verification_id": "v-abc123", "status": "PENDING" }`
`GetVerificationResult`	模板引擎 → 控制平面	gRPC / HTTP	`{ "verification_id": "v-abc123" }`	`{ "status": "APPROVED", "violations": [], "signed_manifest": "..." }`
`VerificationCallback`	控制平面 → 模板引擎	HTTP POST (Webhook)	`{ "verification_id": "v-abc123", "status": "REJECTED", "violations": [ {"policy": "no-privileged-containers", "severity": "HIGH"} ] }`	`HTTP 200 OK`

SubmitVerification

模板引擎 → 控制平面

gRPC

{
  "cluster_id": "prod-01",
  "namespace": "default",
  "resources": [ ... ],
  "template_meta": {
    "name": "my-app",
    "version": "1.2.3"
  }
}

{
  "verification_id": "v-abc123",
  "status": "PENDING"
}

GetVerificationResult

模板引擎 → 控制平面

gRPC / HTTP

{
  "verification_id": "v-abc123"
}

{
  "status": "APPROVED",
  "violations": [],
  "signed_manifest": "..."
}

VerificationCallback

控制平面 → 模板引擎

HTTP POST (Webhook)

{
  "verification_id": "v-abc123",
  "status": "REJECTED",
  "violations": [
    {"policy": "no-privileged-containers", "severity": "HIGH"}
  ]
}

HTTP 200 OK

集成风险提示：控制平面的核验结果必须包含不可否认性签名，防止中间人篡改核验结论。模板引擎在收到 REJECTED 状态后，应立即阻断后续部署流水线，并将违规详情写入审计日志。

4.5 架构决策记录（ADR）

以下为本集成方案的关键架构决策，供团队评审与后续演进参考。

ADR-001：模板引擎不直接调用策略引擎，而是通过控制平面进行代理。原因：策略引擎的版本升级、策略热加载、缓存机制由控制平面统一管理，降低模板引擎的复杂度。
ADR-002：核验请求采用异步模式，模板引擎在提交后立即获得 PENDING 状态，并通过回调或轮询获取最终结果。原因：基线核验可能涉及多策略组合、外部系统查询（如漏洞库），同步模式会导致模板引擎超时。
ADR-003：控制平面维护核验结果缓存（TTL 5 分钟），对于相同资源清单的重复提交直接返回缓存结果。原因：CI 流水线中多次触发相同模板渲染时，避免重复核验造成性能浪费。
ADR-004：所有核验结果必须持久化到审计数据库（如 PostgreSQL / Elasticsearch），保留至少 90 天。原因：满足合规审计要求，支持事后追溯与策略调优。