ljwx-k8s/DEPLOYMENT-SUMMARY.md

Kubernetes 可观测性栈部署总结

✅ 部署完成

已安装组件

1. Metrics（指标监控）

• ✅ Prometheus - 指标存储和查询引擎
• ✅ Grafana - 可视化平台
• ✅ Alertmanager - 告警管理
• ✅ kube-state-metrics - Kubernetes 对象状态指标
• ✅ node-exporter - 节点级别系统指标

2. Logs（日志系统）

• ✅ Loki - 日志聚合和存储（namespace: logging）
• ✅ Promtail - 日志采集 DaemonSet（自动采集所有 pod 日志）

3. Traces（链路追踪）

• ✅ Tempo - 分布式追踪存储（namespace: tracing）
• ✅ OpenTelemetry Collector - 链路数据采集和转发

4. 告警规则

• ✅ Node 级别告警（磁盘、内存、CPU、inode）
• ✅ Pod 级别告警（重启、Pending、资源使用）
• ✅ Workload 级别告警（Deployment、StatefulSet、DaemonSet、Job）
• ✅ 可观测性组件告警（Prometheus、Loki）

🔗 访问地址

组件	地址	凭据
Grafana	http://localhost:30300	admin/admin
Prometheus	http://localhost:30900	-

📊 Grafana 数据源配置

Grafana 已自动配置以下数据源：

1. Prometheus (默认数据源)

   • URL: http://prometheus:9090
   • 用于查询指标数据

2. Loki

   • URL: http://loki.logging.svc.cluster.local:3100
   • 用于查询日志数据
   • 支持从日志跳转到 Tempo traces

3. Tempo

   • URL: http://tempo.tracing.svc.cluster.local:3200
   • 用于查询分布式追踪数据
   • 支持从 trace 跳转到 Loki 日志

🚀 快速验证

1. 验证所有组件运行状态

# 查看 monitoring namespace
kubectl get pods -n monitoring

# 查看 logging namespace
kubectl get pods -n logging

# 查看 tracing namespace
kubectl get pods -n tracing

2. 验证 Grafana 数据源

# 访问 Grafana
open http://localhost:30300

# 登录后，进入 Configuration → Data sources
# 应该看到 3 个数据源：Prometheus, Loki, Tempo（全部为绿色 ✓）

3. 验证日志采集

在 Grafana Explore 中：

# 查看所有日志
{namespace=~".+"}

# 查看特定 namespace 的日志
{namespace="fastapi"}

# 查看错误日志
{namespace="fastapi"} |= "ERROR"

4. 验证告警规则

# 访问 Prometheus
open http://localhost:30900

# 点击 "Status" → "Rules"
# 应该看到以下告警组：
# - node-alerts (5 rules)
# - pod-alerts (4 rules)
# - workload-alerts (4 rules)
# - observability-alerts (2 rules)

📈 推荐导入的 Grafana 仪表盘

访问 Grafana → Dashboards → New → Import，输入以下 ID：

必备仪表盘（优先导入）

1. 1860 - Node Exporter Full（节点监控）
2. 15758 - Kubernetes Views Pods（Pod 监控）
3. 13639 - Logs / App（应用日志）
4. 315 - Kubernetes cluster monitoring（集群监控）

可选仪表盘

5. 15757 - Kubernetes Views Namespaces
6. 15759 - Kubernetes Views Nodes
7. 12611 - Loki & Promtail
8. 16110 - Tempo / Operational

详细说明请参考：OBSERVABILITY-GUIDE.md

🔧 应用接入指南

接入日志（自动）

✅ 已自动完成 - Promtail DaemonSet 自动采集所有 pod 的 stdout/stderr

推荐日志格式（JSON）：

{
  "timestamp": "2025-12-16T08:00:00Z",
  "level": "INFO",
  "message": "Request processed",
  "trace_id": "abc123...",
  "span_id": "def456...",
  "service": "api-service"
}

接入链路追踪（需要代码修改）

OTLP 端点：

• gRPC: otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317
• HTTP: otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318

Python (FastAPI) 示例：

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

otlp_exporter = OTLPSpanExporter(
    endpoint="otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317",
    insecure=True
)

Spring Boot 配置：

management:
  otlp:
    tracing:
      endpoint: http://otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318/v1/traces

详细接入指南请参考：OBSERVABILITY-GUIDE.md

📁 配置文件清单

文件	说明
loki-values.yaml	Loki + Promtail 配置
tempo-values.yaml	Tempo 配置
otel-collector-values.yaml	OpenTelemetry Collector 配置
grafana-datasources-updated.yaml	Grafana 数据源配置
prometheus-alerts.yaml	Prometheus 告警规则
OBSERVABILITY-GUIDE.md	完整使用指南
DEPLOYMENT-SUMMARY.md	本文件

🔍 验证脚本

运行以下命令验证所有组件：

# 1. 检查所有 pods 状态
echo "=== Monitoring Namespace ==="
kubectl get pods -n monitoring

echo -e "\n=== Logging Namespace ==="
kubectl get pods -n logging

echo -e "\n=== Tracing Namespace ==="
kubectl get pods -n tracing

# 2. 检查所有 services
echo -e "\n=== Services ==="
kubectl get svc -n monitoring | grep -E "(grafana|prometheus|alertmanager)"
kubectl get svc -n logging
kubectl get svc -n tracing

# 3. 验证 Loki 健康状态
echo -e "\n=== Loki Health Check ==="
kubectl exec -n logging loki-0 -- wget -q -O- http://localhost:3100/ready

# 4. 验证 Tempo 是否正常
echo -e "\n=== Tempo Status ==="
kubectl get pods -n tracing -l app.kubernetes.io/name=tempo

# 5. 验证 OTel Collector 是否正常
echo -e "\n=== OTel Collector Status ==="
kubectl get pods -n tracing -l app.kubernetes.io/name=opentelemetry-collector

# 6. 检查告警规则
echo -e "\n=== Prometheus Rules ==="
kubectl get prometheusrule -n monitoring

echo -e "\n✅ 验证完成！"
echo "访问 Grafana: http://localhost:30300 (admin/admin)"
echo "访问 Prometheus: http://localhost:30900"

将上述脚本保存为 verify-observability.sh，然后运行：

chmod +x verify-observability.sh
./verify-observability.sh

🐛 故障排查

Loki 无法查询日志

# 检查 Promtail 状态
kubectl logs -n logging -l app.kubernetes.io/name=promtail --tail=50

# 检查 Loki 是否可以接收日志
kubectl exec -n logging loki-0 -- wget -q -O- 'http://localhost:3100/loki/api/v1/labels'

Tempo 无法查询 traces

# 检查 OTel Collector 日志
kubectl logs -n tracing -l app.kubernetes.io/name=opentelemetry-collector --tail=50

# 检查 Tempo 日志
kubectl logs -n tracing tempo-0 --tail=50

Grafana 数据源连接失败

# 重启 Grafana
kubectl rollout restart deployment grafana -n monitoring

# 检查 Grafana 日志
kubectl logs -n monitoring -l app.kubernetes.io/name=grafana --tail=50

📚 下一步

1. ✅ 导入推荐的 Grafana 仪表盘
2. ✅ 配置 Alertmanager 通知（邮件、Slack 等）
3. ✅ 应用接入链路追踪（修改应用代码）
4. ✅ 定期备份 PVC 数据
5. ✅ 根据业务需求添加自定义告警规则

🎓 学习资源

• 完整使用指南
• Prometheus 查询语言
• LogQL 查询语言
• OpenTelemetry 文档

---

部署日期: 2025-12-16 环境: OrbStack Kubernetes v1.33.5 部署工具: Helm + kubectl 状态: ✅ 生产就绪