holmesgpt-skill

HolmesGPT Skill

面向 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 credentials	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