oodle-onboarding

Oodle オンボーディング — インテグレーションのセットアップ

oodle integrations コマンドを使用して、インフラストラクチャを Oodle オブザーバビリティプラットフォームと統合します。環境を積極的に調査し、適切なインテグレーションを推奨するとともに、セットアップ手順を調整してください。セットアップ仕様は設計図です。方針とパラメーターを定義しますが、実行内容はコードベースと環境から判明した情報に応じて調整します。

前提条件

オンボーディング作業を始める前に、Oodle CLI がインストールされ、認証済みであることを確認してください。各セッションの開始時に、次のチェックを実行します。

手順 1：CLI がインストールされているか確認する

oodle version

コマンドが見つからない場合は、インストールします。

brew install oodle-ai/oodle/oodle

brew を利用できない場合は、次の方法を使用します。

go install github.com/oodle-ai/oodle-cli/cmd/oodle@latest

手順 2：CLI が認証済みか確認する

oodle auth status

認証されていない場合、またはステータスにエラーが表示される場合は、対話型ログインを実行します。

oodle auth login

OAuth ログイン用のブラウザーが開きます。ユーザーがブラウザーでの手続きを完了する必要があるため、完了するよう案内し、確認を待ってください。ログインに成功したら、oodle auth status で確認します。

注： oodle integrations list-setup-specs と oodle integrations get-setup-spec の実行に認証は不要です。これらを使えば、認証設定前でも利用可能なインテグレーションを確認し、セットアップ手順を取得できます。その他のインテグレーションコマンドには有効な認証情報が必要です。コマンド実行順序の手順 2 以降に進む前に、上記の認証手順を完了してください。

コマンドの実行順序

インテグレーションのオンボーディング依頼ごとに、次の順序に従ってください。

1. インテグレーションの種類を特定します。 ユーザーが種類を指定した場合（例：「kubernetes」、「aws-cloudwatch」）は、それを使用します。指定がない場合は、環境を調査して、存在するインフラストラクチャを検出し、一致するインテグレーションを推奨します（references/environment-discovery.md を参照）。
2. 利用可能なセットアップ仕様を取得します — oodle integrations list-setup-specs -o json を実行します（認証不要）。指定された種類が存在することを確認し、検出結果と照合します。
3. インテグレーションのレコードを取得します — oodle integrations list -o json を実行して、次の情報を抽出します。（a）type フィールド（手順 4 のために小文字に変換）、（b）helm の値に使用する collectorDomain／logsCollectorDomain、（c）ドメインのパターンから得られるインスタンス ID。その後、oodle api-keys list -o json を実行して既存の API キーを探すか、見つからない場合は oodle api-keys create --name <name> --scopes <scopes> を実行して作成します。認証が必要です。未設定の場合は、まず前提条件の手順 1～2 を完了してください。
4. セットアップ仕様を取得します — oodle integrations get-setup-spec <type-lowercase> -o json を実行します。これはインテグレーションの設計図であり、厳密に従うスクリプトではありません。全般的な方針、必要なツール、パラメーターを定義しています。
5. 環境を詳しく調査します — コードベース、実行中のサービス、既存の設定を調べます。調査結果をもとにパラメーターを確定し、仕様の手順を調整します（references/environment-discovery.md を参照）。
6. 残りのパラメーターを収集します — 調査後、自動検出できなかった項目についてユーザーに質問します。質問はまとめて提示してください。
7. セットアップを実行します — 調査結果に基づいて各手順を調整しながら、仕様の手順を進めます。読み取り専用でないコマンドを実行する前に、必ずユーザーに確認してください。実行前に references/gotchas.md を確認してください。
8. インテグレーションを検証します — oodle integrations list -o json を実行し、ステータスを確認します。
9. Oodle 側でデータの存在を確認します（references/post-install-validation.md を参照）。

失敗時の対応については、references/failure-handling.md を参照してください。

クイックリファレンス

タスク	コマンド	認証が必要ですか？
利用可能なセットアップ仕様を確認する	oodle integrations list-setup-specs -o json	いいえ
利用可能なセットアップ仕様を確認する（テーブル形式）	oodle integrations list-setup-specs	いいえ
セットアップ仕様を取得する	oodle integrations get-setup-spec <type> -o json	いいえ
セットアップ仕様を取得する（YAML形式）	oodle integrations get-setup-spec <type> -o yaml	いいえ
設定済みの連携を一覧表示する	oodle integrations list -o json	はい
設定済みの連携を一覧表示する（テーブル形式）	oodle integrations list	はい
API キーを一覧表示する	oodle api-keys list -o json	はい
API キーを作成する	oodle api-keys create --name <name> --scopes <scopes> -o json	はい

エイリアス：oodle integration、oodle integ

一般的な操作

利用可能な連携タイプの確認

# CORRECT — discover all types with setup specs (no auth required)
oodle integrations list-setup-specs -o json

# CORRECT — table output for display (no auth required)
oodle integrations list-setup-specs

# WRONG — guessing integration types without checking
oodle integrations get-setup-spec some-random-type -o json

設定済みの連携の一覧表示

# CORRECT — check which integrations are already configured (requires auth)
oodle integrations list -o json

# CORRECT — table output for display
oodle integrations list

セットアップ仕様の取得

# CORRECT — fetch spec for a known type (no auth required)
oodle integrations get-setup-spec kubernetes -o json

# WRONG — hardcoding setup steps instead of fetching the spec
kubectl apply -f <hardcoded-collector-manifest>   # never hardcode a manifest source; fetch the spec instead

セットアップ手順の実行（設計図に合わせて調整）

仕様では、必要な作業が定義されています。各手順の前に現在の状態を確認し、それに合わせて調整してください。

# CORRECT — check existing state, then adapt
kubectl get namespace oodle-system 2>/dev/null && echo "Already exists, skipping" || kubectl create namespace oodle-system

# CORRECT — existing release? upgrade instead of install
helm list -n oodle-system | grep oodle && helm upgrade ... || helm install ...

# CORRECT — show the command and ask for confirmation before running
echo "I will run: kubectl create namespace oodle-system"
# [wait for user confirmation]
kubectl create namespace oodle-system

# WRONG — blindly running spec commands without checking existing state
kubectl create namespace oodle-system  # fails if already exists

# WRONG — running destructive commands without confirmation
kubectl delete namespace oodle-system

連携の検証

# CORRECT — check integration status after setup
oodle integrations list -o json

# CORRECT — check pods are running (for Kubernetes integrations)
kubectl get pods -n oodle-system

# WRONG — assuming success without verification
echo "Integration complete!"

ベストプラクティス

常に最新のセットアップ仕様を取得する

オンボーディングセッションを開始するたびに、oodle integrations get-setup-spec <type> -o json を実行してください。取得済みの仕様をキャッシュしたり再利用したりしないでください。プラットフォームの進化に伴い、要件や手順は変更されます。仕様は設計図として扱ってください。必要な作業と必須パラメーターが定義されていますが、具体的なコマンドや値は環境の確認結果に応じて調整してください。

まず確認してパラメーターを特定し、それから質問する

実行を開始する前に、必要なパラメーターをすべて集めてください。次の情報源を順番に確認します。

1. 環境の確認 — 積極的に調べます。クラスター名は kubectl config current-context、既存のリリースは helm list、実行中のコレクターはプロセス一覧、エンドポイントはコードベース内の設定ファイル、API キーは環境変数で確認します。
2. ユーザーのリクエスト — ユーザーがプロンプトで値を指定している場合があります。
3. ユーザーへの質問 — 自動検出できなかった項目だけを尋ねます。残りの質問はまとめて行います。

リソースの作成または変更前に確認を得る

リソースを作成、変更、削除するコマンドを実行する前に、実行するコマンドを提示し、ユーザーの確認を待ってください。読み取り専用のコマンド（list、get、describe）には確認は不要です。提示するコマンド内のシークレットは必ずマスキングしてください。確認にはマスキングしたバージョンを提示し、その後、内部でマスキングしていないバージョンを実行します。シークレット値が必要なコマンド（例：helm install --set apiKey=...）では、シェルの履歴に残るのを避けるため、コマンドライン引数ではなく一時ファイル、標準入力、または環境変数を使ってシークレットを渡すことを優先してください。

既存のリソースには適切に対応する

リソース（名前空間、Helm リリース、ConfigMap）がすでに存在する場合は、作成手順を省略し、すでに存在していたことを記録してください。失敗したり、削除して再作成しようとしたりしないでください。

出力内のシークレットをマスキングする

API キー、トークン、パスワードを完全な形で表示しないでください。最初の4文字と最後の4文字だけを表示します（例：oodl...k9x2）。仕様から設定テンプレートを表示する際は、ユーザーに見せる前にシークレット値をマスキングしてください。

一度に一つの手順を進める

セットアップ手順は順番に実行してください。次の手順に進む前に、それぞれの手順が成功したことを確認します。手順が失敗した場合は、問題を診断して修正を提案し、次の手順には進まないでください。

完了後に概要を提示する

すべての手順が完了し、検証に合格したら、次の内容をまとめて提示してください。

• 連携のタイプと名前
• インストールまたは設定した内容
• 現在のステータス
• 後でステータスを確認する方法（oodle integrations list）

参考資料

• references/environment-discovery.md — インフラストラクチャの検出とセットアップ手順の適応
• references/gotchas.md — セットアップを実行する前に確認すべき重要な注意点
• references/post-install-validation.md — クエリスキルを使ったデータの存在確認
• references/failure-handling.md — よくある失敗ケースのトラブルシューティング
• Oodle CLI リポジトリ — oodle バイナリのソース
• Oodle ドキュメント — 製品ドキュメント
• oodle-cli スキル — CLI の基本的な使い方、認証、出力形式