holmesgpt

HolmesGPT スキル

Kubernetes およびクラウドネイティブ環境向けの AI を活用したトラブルシューティングです。

概要

HolmesGPT は、AI モデルとリアルタイムのオブザーバビリティデータを連携させ、インフラの問題を調査し、根本原因を特定して、修正方法を提案する CNCF Sandbox プロジェクトです。読み取り専用アクセスで動作し、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.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はデフォルトでSecretを参照できません： Secret参照の設定ミスが関係する調査では、エージェントが原因の可能性として指摘していても、「読み取り権限がありません」と返されます。特定のnamespaceに対して secrets:get を許可するか、この見落としを受け入れてください。クラスター全体に権限を広げないでください。
• 大規模環境では、ツールセットの有効化が累積し、ノイズも増えます： 30以上のツールセットをすべて有効にすると、LLMが無関係なデータを調べ、精度が低下します。スタックに合ったツールセットだけを有効にしてください。追加するたびにトークンを消費し、根本原因の分析にノイズが加わります。
• 再現性のある調査には、モデルのtemperatureを必ず0にしてください： Helmのデフォルト値でtemperatureが0より大きい場合があり、同じアラートでも実行ごとに異なる根本原因が示されます。modelListで temperature: 0 を固定してください。固定しない場合は、実行ごとの結果を比較することになり、信頼性が損なわれます。
• AlertManagerのURLには、CLIではなくHolmesGPT Podからアクセスできる必要があります： 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のエラーメッセージは「model not found」と表示しますが、欠けているプレフィックスは示しません。