📚 课程目录第4章 Terraform状态文件SLI

4. Terraform 状态文件 SLI：状态锁争用率、状态文件版本偏差、状态文件损坏检测频率

Terraform 状态文件（terraform.tfstate）是基础设施即代码的核心资产，记录了资源与真实世界的映射关系。状态文件的健康度直接决定变更操作的可靠性与一致性。本章定义三个关键 SLI，用于量化状态文件的稳定性与可用性。

4.1 SLI 一：状态锁争用率

当多个用户或 CI/CD 流水线同时尝试对同一状态文件执行写入操作时，后端锁机制（如 DynamoDB、Consul、Pg）会阻止并发写入。高争用率意味着团队协作效率下降，变更排队时间延长。

SLI 名称	状态锁争用率
口径定义	在统计周期内，因状态锁被持有而获取锁失败的请求次数 ÷ 总写入请求次数 × 100%
采集方法	从 Terraform 后端日志或锁表（如 DynamoDB ConditionCheck 失败记录）中提取 `acquire lock failed` 事件，除以总 `apply` 与 `destroy` 操作数
推荐阈值	争用率 < 5% 为健康；5%–15% 需关注；> 15% 需立即优化锁超时或拆分工作空间
数据源示例	AWS DynamoDB 表 `terraform-lock` 的 `ConditionalCheckFailedException` 指标；或 Consul session 失效日志

🔧 采集脚本片段（AWS DynamoDB 后端）：

# 从 CloudWatch Logs 中提取锁争用事件
aws logs filter-log-events \
  --log-group-name "/aws/terraform/state-lock" \
  --filter-pattern "ConditionalCheckFailedException" \
  --start-time $(date -d '1 hour ago' +%s) \
  --query 'events[*].message' | grep -c "acquire lock failed"

# 总写入请求数 = apply + destroy 操作数
aws logs filter-log-events \
  --log-group-name "/aws/terraform/apply" \
  --filter-pattern "Terraform apply succeeded" \
  --start-time $(date -d '1 hour ago' +%s) \
  --query 'events[*].message' | wc -l

💡 最佳实践： 为每个 Terraform 工作空间（workspace）设置独立的锁表或锁键，避免全局锁争用。使用 terraform force-unlock 前必须人工确认持有者已离线。

4.2 SLI 二：状态文件版本偏差

状态文件版本偏差指本地缓存的状态文件版本与后端最新版本之间的差异。偏差过大会导致 terraform plan 基于过期数据生成错误计划，甚至引发资源漂移误报。

SLI 名称	状态文件版本偏差
口径定义	在统计周期内，检测到本地状态文件 serial 值落后于后端最新 serial 值的操作次数 ÷ 总状态读取操作次数 × 100%
采集方法	在 `terraform plan` 或 `terraform refresh` 执行前，比较本地 `.terraform/terraform.tfstate` 的 `serial` 字段与后端存储（S3/GCS/Azure Storage）中最新文件的 `serial` 字段
推荐阈值	版本偏差率 < 2% 为健康；2%–10% 需检查 CI/CD 缓存策略；> 10% 必须强制刷新状态
数据源示例	本地 `terraform.tfstate` JSON 中的 `serial` 键；后端 S3 对象元数据或 GCS 对象 generation 号

⚠️ 常见陷阱： 部分 CI/CD 系统会缓存 .terraform 目录以加速流水线，但若缓存未随状态更新而失效，将导致持续版本偏差。建议在流水线中每次执行 terraform init -reconfigure 或显式删除缓存目录。

4.3 SLI 三：状态文件损坏检测频率

状态文件损坏包括 JSON 语法错误、字段缺失、资源引用断裂或校验和不匹配。损坏的状态文件会导致 terraform plan 崩溃或产生不可逆的变更计划。

SLI 名称	状态文件损坏检测频率
口径定义	在统计周期内，通过自动化校验发现状态文件损坏的次数 ÷ 总状态文件读取次数 × 100%
采集方法	每次读取状态文件后，执行 `terraform validate` 或自定义 JSON Schema 校验；同时计算后端存储提供的 MD5/CRC32C 校验和与本地计算值是否一致
推荐阈值	损坏频率 < 0.1% 为健康；0.1%–1% 需检查存储后端一致性；> 1% 必须启用状态文件备份与版本控制
数据源示例	S3 对象 ETag 与本地 MD5 对比；GCS 对象 crc32c 校验；Terraform 日志中的 `Error loading state: json: cannot unmarshal` 事件

🔧 自定义校验脚本示例：

#!/bin/bash
# 校验状态文件 JSON 语法与 serial 完整性
STATE_FILE="terraform.tfstate"

# 1. JSON 语法校验
if ! jq empty "$STATE_FILE" 2>/dev/null; then
  echo "FAIL: JSON syntax error in $STATE_FILE"
  exit 1
fi

# 2. 校验 serial 字段存在且为正整数
SERIAL=$(jq -r '.serial // empty' "$STATE_FILE")
if [[ ! "$SERIAL" =~ ^[0-9]+$ ]]; then
  echo "FAIL: serial field missing or invalid in $STATE_FILE"
  exit 1
fi

# 3. 校验 resources 数组非空
RESOURCE_COUNT=$(jq '.resources | length' "$STATE_FILE")
if [[ "$RESOURCE_COUNT" -eq 0 ]]; then
  echo "WARN: state file contains zero resources"
fi

echo "PASS: state file integrity check succeeded (serial=$SERIAL, resources=$RESOURCE_COUNT)"

4.4 三个 SLI 的采集架构

下图展示了从 Terraform 操作到 SLI 指标汇聚的完整数据流，涵盖锁事件、版本偏差检测与损坏校验三个采集路径。

4.5 口径定义与采集方法总结

下表汇总三个 SLI 的口径定义、采集频率与数据源，便于在可靠性评审报告中直接引用。

SLI	口径公式	采集频率	主要数据源
状态锁争用率	锁失败请求数 ÷ 总写入请求数 × 100%	每次 apply/destroy 后实时采集	DynamoDB ConditionCheckFailedException / Consul session 日志
状态文件版本偏差	版本落后操作数 ÷ 总读取操作数 × 100%	每次 plan/refresh 前采集	本地 serial vs 后端 serial（S3 对象元数据 / GCS generation）
状态文件损坏检测频率	损坏检测次数 ÷ 总读取次数 × 100%	每次读取状态文件后采集	jq JSON 校验 + S3 ETag / GCS crc32c 校验和

💡 评审报告建议： 在可靠性评审报告中，将三个 SLI 以时间序列折线图呈现，并标注 P99 与 P95 分位线。锁争用率与版本偏差通常呈正相关——高争用期往往伴随版本偏差上升，建议在报告中分析两者的联动关系。