4. 配置文件结构：YAML 配置文件的设计原则

在 Kubernetes 环境容量压测巡检脚本中，YAML 配置文件是连接脚本逻辑与集群环境的“契约”。一个设计良好的配置文件应当遵循可读性优先、职责分离、默认值兜底三大原则。本章将围绕集群信息、压测参数、巡检阈值三个核心模块，拆解 YAML 配置的结构设计与调试要点。

4.1 配置文件整体结构

一个标准的压测巡检 YAML 配置文件包含三个顶级字段：cluster、stress、inspection。以下为完整结构示例：

# kubernetes-stress-inspection-config.yaml
# 版本: v2.1
# 用途: 集群容量压测与巡检参数配置

cluster:
  name: "production-cluster-01"
  kubeconfig: "/home/sre/.kube/config"
  context: "prod-context"
  namespace: "stress-test"
  timeout: 30s

stress:
  mode: "deployment"          # 可选: deployment / job / statefulset
  replicas: 10
  cpu_limit: "500m"
  memory_limit: "512Mi"
  duration: "5m"
  concurrency: 3
  image: "registry.example.com/stress-ng:latest"
  node_selector:
    kubernetes.io/hostname: "node-01"

inspection:
  interval: 10s
  thresholds:
    cpu_usage_percent: 80
    memory_usage_percent: 85
    pod_restart_count: 3
    node_disk_pressure: false
    api_server_latency_ms: 500
    etcd_db_size_mb: 100

4.2 集群信息模块（cluster）

cluster 区块负责定义脚本如何连接目标 Kubernetes 集群。它不包含任何压测或巡检逻辑，只提供连接上下文。

4.3 压测参数模块（stress）

stress 区块控制压测任务的执行方式。它决定了脚本创建什么样的工作负载、运行多长时间、以及如何调度到节点上。

4.4 巡检阈值模块（inspection）

inspection 区块定义脚本在压测过程中持续监控哪些指标，以及触发告警的阈值。阈值设置过高会漏报，过低则导致误报，需要根据集群基线反复校准。

4.5 配置文件结构关系图

下图展示了 YAML 配置文件中三个模块之间的数据流向与依赖关系：

4.6 参数调试与校验流程

在将配置文件投入正式压测前，建议按以下步骤进行调试与校验：

1. 语法校验：使用 python -c "import yaml; yaml.safe_load(open('config.yaml'))" 检查 YAML 格式是否正确。
2. 字段完整性检查：脚本启动时自动校验必填字段是否存在，缺失时打印错误并退出。
3. 集群连通性测试：脚本先执行 kubectl cluster-info 验证 cluster 模块配置是否有效。
4. 压测参数合理性检查：例如 replicas 不能为 0，duration 不能小于 30 秒。
5. 阈值范围检查：百分比阈值应在 0~100 之间，延迟阈值应为正数。

import yaml
import sys

def validate_config(path):
    with open(path, 'r') as f:
        config = yaml.safe_load(f)
    
    required = ['cluster', 'stress', 'inspection']
    for key in required:
        if key not in config:
            raise ValueError(f"缺少顶级字段: {key}")
    
    # 校验 cluster 必填字段
    cluster = config['cluster']
    if 'name' not in cluster or 'namespace' not in cluster:
        raise ValueError("cluster 模块缺少 name 或 namespace")
    
    # 校验 stress 必填字段
    stress = config['stress']
    if 'mode' not in stress or 'replicas' not in stress or 'duration' not in stress:
        raise ValueError("stress 模块缺少 mode/replicas/duration")
    
    print("配置文件校验通过")
    return config

if __name__ == "__main__":
    validate_config(sys.argv[1])

4.7 多环境配置管理建议

在实际 SRE 工作中，通常需要管理开发、测试、预发、生产等多套环境的配置。推荐以下管理策略：

• 环境变量覆盖：YAML 中支持 ${ENV_VAR} 占位符，脚本在加载时自动替换。例如 namespace: "stress-${ENV}"。
• 配置分层：将公共参数放在 base.yaml，环境差异参数放在 dev.yaml / prod.yaml，脚本启动时合并。
• 版本控制：所有 YAML 配置文件纳入 Git 仓库，每次修改附带变更记录。
• 配置热加载：巡检脚本支持 SIGHUP 信号重新加载配置文件，无需重启进程即可调整阈值。