📚 课程目录第3章 SLO作业模板设计原则

3. SLO 作业模板设计原则：可复用性、可配置性、版本控制、自动化验证

SLO 作业模板是平台工程中连接“SLO 定义”与“基础设施即代码（IaC）部署”的核心契约。一个设计良好的模板，必须同时满足四个关键原则：可复用性、可配置性、版本控制和自动化验证。这四项原则共同决定了 SLO 作业能否在规模化环境中稳定、高效地运行。

3.1 四大设计原则总览

下表从定义、核心关注点、典型反模式三个维度，对比了四项原则的差异与互补关系：

原则	定义	核心关注点	典型反模式
可复用性	模板能在不同服务、不同环境（开发/预发/生产）中重复使用，无需重复编写核心逻辑。	抽象通用结构，避免硬编码服务名、环境名、指标名。	每个服务都复制一份模板，然后手动修改所有字段。
可配置性	通过外部参数或变量文件，在不修改模板代码的前提下，改变 SLO 目标、时间窗口、告警阈值等行为。	分离“模板逻辑”与“实例配置”。	将 SLO 目标值直接写在模板的 YAML 或 HCL 文件中。
版本控制	模板本身及其生成的作业实例，都纳入 Git 等版本管理系统，支持变更追溯、回滚和协作。	模板与实例的版本关联、变更记录。	在 IaC 工具控制台直接编辑作业，不提交代码。
自动化验证	在模板提交或作业部署前，通过 CI/CD 流水线自动检查模板语法、参数合法性、SLO 目标合理性。	集成 lint、validate、dry-run 等检查步骤。	手动部署后才发现模板参数错误导致作业失败。

3.2 可复用性：抽象通用结构

可复用性的核心是模板抽象。平台团队需要识别出所有 SLO 作业的公共骨架，将其封装为模板，而将服务特定的部分暴露为变量。

模板抽象示例（Terraform + Prometheus Operator）：

# slo-template.tf - 通用 SLO 作业模板
resource "prometheus_rule_group" "slo_rule" {
  name     = "${var.service_name}-slo-rules"
  interval = var.evaluation_interval

  rule {
    record = "${var.service_name}:slo:error_budget_remaining"
    expr   = <<EOT
      1 - (
        sum(rate(${var.metric_name}{${var.filter_selector}, status=~"5.."}[${var.window_duration}]))
        /
        sum(rate(${var.metric_name}{${var.filter_selector}}[${var.window_duration}]))
      )
    EOT
    labels = {
      service = var.service_name
      slo     = var.slo_target
    }
  }
}

上述模板中，var.service_name、var.metric_name、var.slo_target 等变量，使得同一个模板文件可以为“订单服务”、“支付服务”、“用户服务”分别生成不同的 SLO 作业。

3.3 可配置性：参数化驱动

可配置性要求模板的行为可以通过外部输入改变，而不需要修改模板代码。常见的配置维度包括：

SLO 目标值：例如 99.9%、99.99%。
时间窗口：例如 30 天、7 天、1 小时。
告警阈值：例如错误预算剩余 10% 触发告警。
指标选择器：例如特定集群、命名空间、标签。
评估频率：例如每 1 分钟、每 5 分钟。

配置分层策略：

默认配置：模板内嵌合理的默认值（如 SLO 目标 99.9%）。
环境配置：通过 environments/prod.tfvars 覆盖生产环境参数。
服务配置：每个服务维护独立的 slo-config.yaml 文件。

3.4 版本控制：模板与实例的关联

版本控制不仅管理模板代码，还需要管理模板生成的作业实例。推荐采用“模板仓库 + 实例仓库”的双层结构：

版本控制避坑指南：

不要将模板文件直接复制到实例仓库中，否则无法统一升级。
模板版本号建议使用语义化版本（SemVer），如 v1.2.3。
实例仓库的每次提交，都应记录所引用的模板版本。

3.5 自动化验证：CI/CD 流水线集成

自动化验证是确保 SLO 作业模板质量的关键防线。验证流水线通常包含以下阶段：

自动化验证脚本示例（GitHub Actions）：

# .github/workflows/slo-template-validate.yml
name: SLO Template Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Terraform Format & Validate
        run: |
          terraform fmt -check
          terraform validate
      - name: SLO Parameter Check
        run: |
          # 检查 SLO 目标是否在合理范围
          for config in configs/*.yaml; do
            target=$(yq eval '.slo_target' $config)
            if (( $(echo "$target < 90.0" | bc -l) )); then
              echo "Error: SLO target $target in $config is too low"
              exit 1
            fi
          done
      - name: Terraform Plan (Dry-Run)
        run: terraform plan -out=tfplan
      - name: Prometheus Rule Lint
        run: promtool check rules generated_rules/*.yaml

3.6 四项原则的协同关系

四项原则并非孤立存在，而是形成一个完整的闭环：

可复用性和可配置性共同决定了模板的灵活性——前者解决“能用多少次”，后者解决“能适应多少场景”。
版本控制为自动化验证提供了触发时机和变更上下文——每次版本变更都应触发验证流水线。
自动化验证反过来保障了可复用性和可配置性的正确性——确保参数传递不会破坏模板结构。

平台工程实践建议：

在搭建 SLO 作业模板体系时，建议按照“先抽象（可复用性）→ 再参数化（可配置性）→ 纳入 Git（版本控制）→ 接入 CI（自动化验证）”的顺序逐步推进。不要试图一次性实现所有原则，而是通过迭代逐步完善。