holmesgpt

HolmesGPT 技能

面向 Kubernetes 和云原生环境的 AI 驱动故障排查。

概览

HolmesGPT 是 CNCF Sandbox 项目，可将 AI 模型与实时可观测性数据连接起来，以调查基础设施问题、查找根本原因并建议修复方案。它以只读访问方式运行，并遵循 RBAC 权限，因此可安全用于生产环境。

快速参考

主题	参考文档
安装	references/installation.md
配置	references/configuration.md
数据源	references/data-sources.md
命令	references/commands.md
故障排查	references/troubleshooting.md
HTTP API	references/http-api.md
集成	references/integrations.md

主要功能

• 根因分析：调查告警和集群问题
• 多源集成：30+ 个工具集（K8s、Prometheus、Grafana）
• 告警集成：AlertManager、PagerDuty、OpsGenie、Jira、Slack
• 交互模式：使用 /run、/show、/clear 进行故障排查
• 自定义工具集：通过 YAML 配置扩展专有工具
• CI/CD 集成：自动调查部署失败问题

快速安装

CLI（Homebrew）

brew tap robusta-dev/homebrew-holmesgpt
brew install holmesgpt
export ANTHROPIC_API_KEY="your-key"  # or OPENAI_API_KEY
holmes ask "what pods are unhealthy?"

Kubernetes（Helm）

helm repo add robusta https://robusta-charts.storage.googleapis.com
helm repo update
helm install holmesgpt robusta/holmes -f values.yaml

Docker

docker run -it --net=host \
  -e OPENAI_API_KEY="your-key" \
  -v ~/.kube/config:/root/.kube/config \
  us-central1-docker.pkg.dev/genuine-flight-317411/devel/holmes \
  ask "what pods are crashing?"

常用命令

# Basic investigation
holmes ask "what pods are unhealthy and why?"
holmes ask "why is my deployment failing?"

# Interactive mode
holmes ask "investigate issue" --interactive

# Alert investigation
holmes investigate alertmanager --alertmanager-url http://localhost:9093
holmes investigate pagerduty --pagerduty-api-key <KEY> --update

# With file context
holmes ask "summarize the key points" -f ./logs.txt

# CI/CD integration
holmes ask "why did deployment fail?" --destination slack --slack-token <TOKEN>

支持的 AI 提供商

提供商	环境变量	模型
Anthropic	ANTHROPIC_API_KEY	Sonnet 4、Opus 4.5
OpenAI	OPENAI_API_KEY	GPT-4.1、GPT-4o
Azure OpenAI	AZURE_API_KEY	GPT-4.1
AWS Bedrock	AWS 凭据	Claude 3.5 Sonnet
Google Gemini	GEMINI_API_KEY	Gemini 1.5 Pro
Vertex AI	VERTEXAI_PROJECT	Gemini 1.5 Pro
Ollama	本地安装	Llama 3.1、Mistral

基本 Helm Values 结构

# values.yaml for Kubernetes deployment
image:
  repository: robustadev/holmes
  tag: latest

env:
  - name: ANTHROPIC_API_KEY
    valueFrom:
      secretKeyRef:
        name: holmesgpt-secrets
        key: anthropic-api-key

# Model configuration
modelList:
  sonnet:
    api_key: "{{ env.ANTHROPIC_API_KEY }}"
    model: anthropic/claude-sonnet-4-20250514
    temperature: 0

# Toolsets to enable
toolsets:
  kubernetes/core:
    enabled: true
  kubernetes/logs:
    enabled: true
  prometheus/metrics:
    enabled: true

# Resources
resources:
  requests:
    memory: "1024Mi"
    cpu: "100m"
  limits:
    memory: "1024Mi"

# RBAC (read-only by default)
createServiceAccount: true

交互模式命令

命令	说明
/clear	切换主题时重置上下文
/run	执行自定义命令，并与 AI 分享输出
/show	显示完整的工具输出
/context	查看累积的调查信息

自定义工具集示例

# custom-toolset.yaml
toolsets:
  my-custom-tool:
    description: "Custom diagnostic tool"
    tools:
      - name: check_service_health
        description: "Check health of a specific service"
        command: |
          curl -s http://{{ service_name }}.{{ namespace }}.svc.cluster.local/health
        parameters:
          - name: service_name
            description: "Name of the service"
          - name: namespace
            description: "Kubernetes namespace"

使用方法：holmes ask "check health" -t custom-toolset.yaml

用于集成的 Kubernetes 注解

# Add to Services/Deployments for HolmesGPT context
metadata:
  annotations:
    holmesgpt.dev/runbook: |
      This service handles payment processing.
      Common issues: database connectivity, API rate limits.
      Check: kubectl logs -l app=payment-service

环境变量参考

变量	说明	默认值
HOLMES_CONFIG_PATH	配置文件路径	~/.holmes/config.yaml
HOLMES_LOG_LEVEL	日志详细程度	INFO
PROMETHEUS_URL	Prometheus 服务 URL	-
GITHUB_TOKEN	GitHub API 令牌	-
DATADOG_API_KEY	DataDog API 密钥	-
CONFLUENCE_BASE_URL	Confluence URL	-

最佳实践

1. 使用具体查询：包含命名空间、部署名称和症状
2. 从 Claude Sonnet 4.0/4.5 开始：复杂调查的准确性最佳
3. 启用相关工具集：仅启用所需工具集，以减少干扰
4. 使用交互模式：适用于复杂的多步骤调查
5. 设置运行手册：为已知告警类型提供上下文
6. CI/CD 集成：自动分析部署失败问题

安全注意事项

• HolmesGPT 使用只读访问（仅限 get、list、watch）
• 遵循现有 RBAC 权限
• 绝不修改、创建或删除资源
• API 密钥存储在 Kubernetes Secrets 中
• 数据不会用于模型训练

官方资源

• 文档：https://holmesgpt.dev/
• GitHub：https://github.com/robusta-dev/holmesgpt
• Helm Chart：https://github.com/robusta-dev/holmesgpt/tree/master/helm/holmes
• Slack 社区：Cloud Native Slack

---

注意事项

• 只读 RBAC 意味着 HolmesGPT 默认无法查看 Secrets： 涉及配置错误的 Secret 引用的调查会返回“无权读取”，即使 Agent 将其标记为可能原因。可以授予特定命名空间内的 secrets:get 权限，或接受这一盲点——不要扩大到整个集群。
• 启用的工具集会累积，规模扩大后会产生大量噪声： 启用全部 30 多个工具集会让大模型扫描无关数据，降低准确性。只启用与你的技术栈匹配的工具集——每多启用一个，都会消耗更多 token，并给根因分析增加噪声。
• 为确保调查结果可复现，模型温度必须设为 0： 默认 Helm 值有时会将温度设为大于 0；同一告警在不同运行中会得出不同的根因。请在 modelList 中固定设置 temperature: 0，否则就只能比较多次运行的结果，并逐渐失去信任。
• AlertManager URL 必须能从 HolmesGPT Pod 访问，而不只是从 CLI 访问： holmes investigate alertmanager --alertmanager-url http://localhost:9093 在笔记本电脑上可用，但在集群内会失败——请使用集群内服务 DNS（http://kube-prometheus-stack-alertmanager.monitoring:9093）。
• /clear 不会重置工具集上下文，只会清除对话历史： 之前调查中缓存的工具输出会在会话中保留。较长的交互式会话会累积过时的 Prometheus 数据，污染新的问题。处理互不相关的事件时，请重启 CLI。
• modelList 中的 Anthropic 模型名称需要带上 anthropic/ 前缀： model: claude-sonnet-4-20250514 会因找不到提供商而静默失败；正确写法是 model: anthropic/claude-sonnet-4-20250514。LiteLLM 的错误消息只会提示“找不到模型”，不会指出缺少前缀。