2. SLO 作业模板设计原则

SLO 作业模板是平台工程团队将服务等级目标（SLO）从概念转化为可执行、可观测、可复用的核心载体。模板设计的好坏直接决定了 SLO 在 CI/CD 流水线中的落地效率与维护成本。本章围绕五大设计原则展开：模板化思维、可复用性、可观测性、版本控制、与 CI/CD 解耦。

2.1 模板化思维：从“写死”到“参数化”

模板化思维要求将 SLO 定义中的固定结构与可变参数分离。固定结构包括：SLI 指标类型、合规窗口、燃烧速率算法、告警规则；可变参数包括：服务名称、目标阈值、时间窗口长度、标签/注解。

以下是一个标准化的 SLO 模板结构示例（YAML 格式）：

apiVersion: slo.example.com/v1
kind: ServiceLevelObjective
metadata:
  name: {{ .ServiceName }}-slo
  labels:
    service: {{ .ServiceName }}
    team: {{ .TeamName }}
spec:
  target: {{ .TargetPercent }}          # 例如 99.9
  window: {{ .WindowDuration }}         # 例如 28d
  description: "{{ .Description }}"
  indicator:
    type: {{ .IndicatorType }}          # latency / availability / error-rate
    source:
      prometheus:
        query: {{ .PromQLQuery }}
  burnRate:
    fast:
      window: 5m
      threshold: {{ .FastBurnThreshold }}
    slow:
      window: 1h
      threshold: {{ .SlowBurnThreshold }}
  alerting:
    - name: "HighBurnRate"
      severity: critical
      condition: "burn_rate > {{ .FastBurnThreshold }}"

2.2 可复用性：一次定义，多处使用

可复用性要求模板能够跨服务、跨环境、跨团队使用。通过分层抽象实现：

复用策略示例：

• 继承机制：基础模板 → 服务类型模板 → 环境覆盖 → 团队定制，逐层覆盖参数。
• 组合机制：将 SLI 定义、告警规则、标签集拆分为独立模块，按需组合。
• 库化管理：将常用模板放入 Git 仓库的 templates/ 目录，通过版本标签引用。

2.3 可观测性：模板本身可观测

SLO 模板不仅要定义可观测指标，其自身也应当是可观测的。这意味着模板的生成、变更、应用结果都需要留下可追溯的痕迹。

模板可观测性的三个维度：

1. 模板渲染可观测：每次模板渲染生成 SLO 配置时，记录渲染时间、输入参数、输出内容摘要。
2. 模板变更可观测：模板文件本身的 Git 提交记录、变更 diff、审批人、关联 Issue。
3. 模板应用可观测：SLO 配置被应用到 Prometheus / Alertmanager / 监控平台后，记录应用状态（成功/失败/部分失败）。

以下是一个模板渲染日志的示例结构：

{
  "timestamp": "2025-03-21T10:30:00Z",
  "template": "api-latency-slo.yaml.j2",
  "service": "user-service",
  "environment": "production",
  "params": {
    "target": 99.95,
    "window": "28d",
    "fastBurnThreshold": 10
  },
  "rendered_output_hash": "a1b2c3d4e5f6...",
  "status": "applied",
  "error": null
}

2.4 版本控制：模板即代码

所有 SLO 模板必须纳入版本控制，遵循与代码相同的管理规范。版本控制的核心要求：

版本控制下的模板目录结构示例：

slo-templates/
├── v1/
│   ├── base/
│   │   └── slo-base.yaml.j2
│   ├── http-api/
│   │   └── latency-slo.yaml.j2
│   └── values/
│       └── user-service-prod.yaml
├── v2/
│   ├── base/
│   │   └── slo-base.yaml.j2
│   ├── http-api/
│   │   └── latency-slo.yaml.j2
│   └── values/
│       └── user-service-prod.yaml
├── CHANGELOG.md
└── README.md

2.5 与 CI/CD 解耦：模板独立于流水线

SLO 模板不应与特定的 CI/CD 工具或流水线实现强绑定。解耦的目的是：

• 工具无关性：模板可以在 Jenkins、GitLab CI、GitHub Actions、Argo Workflows 等任意流水线中使用。
• 本地可测试：开发人员可以在本地使用 CLI 工具渲染和验证模板，无需触发流水线。
• 流水线可替换：当 CI/CD 工具迁移或升级时，模板无需修改。

解耦的实现方式：

1. 模板引擎独立：使用标准模板引擎（如 Go template、Jinja2），不依赖流水线内置的变量替换机制。
2. CLI 工具封装：提供独立的 CLI 工具（如 sloctl）负责模板渲染、验证、应用，流水线仅调用该 CLI。
3. 输入输出标准化：模板输入为 JSON/YAML 参数文件，输出为标准的 SLO 配置格式（如 PrometheusRule、Grafana SLO 配置）。
4. 流水线仅编排：流水线只负责触发 CLI、传递参数、收集结果，不参与模板逻辑。

# 在 CI/CD 流水线中（以 GitLab CI 为例）
slo-render:
  stage: deploy
  script:
    - sloctl render --template v2/http-api/latency-slo.yaml.j2 \
                    --values values/${CI_ENVIRONMENT_NAME}.yaml \
                    --output rendered/${CI_PROJECT_NAME}-slo.yaml
    - sloctl validate --file rendered/${CI_PROJECT_NAME}-slo.yaml
    - sloctl apply --file rendered/${CI_PROJECT_NAME}-slo.yaml \
                   --environment ${CI_ENVIRONMENT_NAME}
  artifacts:
    paths:
      - rendered/

2.6 设计原则关系图

以下 SVG 展示了五大设计原则之间的依赖与协同关系：

2.7 原则落地检查清单

团队在设计和评审 SLO 模板时，可使用以下清单进行自检：

遵循以上五大设计原则，平台工程团队可以构建出健壮、灵活、可维护的 SLO 作业模板体系，为后续与 CI/CD 流水线的深度集成奠定坚实基础。