holmesgpt-skill

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 credentials	Claude 3.5 Sonnet
Google Gemini	GEMINI_API_KEY	Gemini 1.5 Pro
Vertex AI	VERTEXAI_PROJECT	Gemini 1.5 Pro
Ollama	Local install	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 チャート：https://github.com/robusta-dev/holmesgpt/tree/master/helm/holmes
• Slack コミュニティ：Cloud Native Slack