はじめに
IBM Bobを使っていると、特定のTaskについて、毎回同じ前提や進め方をPromptで説明したくなることがあります。
例えば、IBM Cloud Account内のResourceを確認する場合でも、次のような条件をあらかじめ決めておきたいと考えました。
- Cloud Resourceに対する操作はRead-onlyとする
- 既存のIBM Cloud CLI Login Sessionを利用する
- Service Instanceを基本単位として整理する
- Region、Resource Group、Service Typeで絞り込めるようにする
- 結果を同じ構成のHTML Reportとして出力する
そこで今回、IBM Cloud Account内のService Instanceを確認し、条件に応じて一覧やHTML Reportを作成するCustom Mode、☁️ IBM Cloud Service Instance Reportを作ってみました。
このModeは、Bob Dojo SessionでCustom Modeの仕組みを試すために作成したSampleです。本記事では、Modeの考え方、導入方法、利用例を紹介します。
本記事で公開するYAMLをDownloadし、Bob Settingsの「モード」画面からImportすると、このCustom Modeを登録して利用できます。IBM Cloud CLIやLoginなど、利用に必要な前提条件については後述します。
本記事およびCustom Modeは、個人による検証結果とSampleの共有です。IBMの公式Documentation、正式なSupport見解、または製品保証を示すものではありません。
Custom Modeにした理由
IBM Cloud Account内のResourceを確認する入口として、IBM Cloud PortalにはResource Listがあります。Account内のResourceを一覧で確認できる公式な画面ですが、ResourceはCategoryごとに分かれており、各Sectionを展開・折りたたみながら確認します。
個々のResourceを探して詳細画面を開くには便利ですが、Account全体にどのServiceがあり、どのRegionやResource Groupに分布しているかを、一目で把握するのは簡単ではありません。また、Resource間の関係やTopologyを確認するための画面でもありません。
CLIを使えば必要な情報を取得できますが、Service Instanceの一覧取得、Resource Group名の補足、RegionやService Typeによる絞り込み、Kubernetes Clusterの整理などには、複数のCommandとParameterを組み合わせる必要があります。CLIに慣れていない場合は、適切なCommandやParameterを調べること自体が負担になります。慣れていても、同じ確認を繰り返すのは手間がかかります。
AI Agentを利用すれば、自然言語の依頼から必要なCommandとParameterを判断し、複数の結果をまとめてReportとして整理できます。ただし、通常のChatで毎回依頼すると、対象範囲、Filter、Read-onlyの境界、Report形式などを繰り返し説明する必要があり、実行するたびに手順や出力が変わる可能性もあります。
そこで、情報の取得・整理・可視化までの流れをCustom Modeとして定義しました。Custom Modeにしておくことで、同じ種類の確認を一定の手順と形式で繰り返し実行しやすくなり、YAMLを共有すれば、Team内でも同じ観点でReportを作成できます。
つまり、Resourceを取得する手段がないからではなく、繰り返し発生する「取得・整理・可視化」のWorkflowを定型化し、手間を減らすことが、今回Custom Modeにした理由です。
Modeでできること
- Account内で参照可能なService Instanceの一覧取得
- Region / Location、Resource Group、Service Typeによる絞り込み
- 複数条件を組み合わせた検索
- 選択したInstanceの詳細確認
- Region、Service、Resource Group、State別の集計
- 検索・Filter付きHTML Reportの生成
- Kubernetes Cluster名、Version、Worker数などの整理
- Report Languageの指定（Defaultは英語）
Service Instanceの参照には、IBM Cloud CLIのRead-only Commandを利用します。
なお、このModeでいうRead-onlyは、IBM Cloud Resourceを変更しないという意味です。HTML Reportを保存するため、指定したLocal DirectoryへのFile作成は許可しています。
Custom Modeの構成
BobのCustom Modeでは、例えば次のような項目をYAMLで定義できます。
-
slug：Modeを識別するための名前 -
name：Mode選択画面に表示する名前 -
description：Modeの概要 -
roleDefinition：Bobに与える役割 -
whenToUse：どのようなTaskで利用するか -
customInstructions：具体的な手順や制約 -
groups：利用を許可するTool
今回のYAMLでは、単に「Service Instanceを検索する」という手順だけでなく、Credentialの扱い、禁止する変更操作、Kubernetesの整理方法、Reportの保存先、Error発生時の振る舞いも定義しています。
YAMLの冒頭は次のような構成です。以下は概要を示すための抜粋であり、完全版ではありません。
customModes:
- slug: ibmcloud-service-instance-report
name: ☁️ IBM Cloud Service Instance Report
description: Read-only IBM Cloud service instance discovery and HTML reporting
roleDefinition: >-
You are a read-only IBM Cloud service instance discovery
and reporting assistant.
# whenToUse、customInstructions、groupsなどは完全版を参照
完全版YAMLを入手する
Custom ModeのYAMLは長いため、本記事には全体を埋め込まず、GitHub Repositoryで公開しています。
- Repositoryを見る：IBMBob-and-IBMCloud
- 内容を確認する：GitHubでYAMLを表示
- Copy / Downloadする：Raw YAMLを開く
すでに.bob/custom_modes.yamlが存在し、YAMLを手動で追加する場合は、ファイル全体を上書きせず、customModes:配下へ今回のMode定義を追加してください。
認証と安全性
利用者がTerminalでIBM Cloud CLIにLoginし、Bobはその既存Sessionを利用します。
ibmcloud login
Modeは最初に、以下のようなCommandでCLIとLogin状態を確認します。
ibmcloud version
ibmcloud target
API Key、Password、Access TokenなどをPromptやYAMLに記載しないでください。Loginが必要な場合は、利用者自身がTerminalで実施します。
また、ModeのInstructionでは、Cloud Resourceに対する以下の操作を禁止しています。
- Resourceの作成、更新、再起動、削除
- TagやService Keyの追加、変更、削除
- IAM Policy、Access Group、Service IDの変更
- Resource Group、Account、Billing設定の変更
- CLI Pluginの自動Install・Update
HTML Reportの保存先は、次のDirectoryに制限しています。
ibmcloud-service-instance-reports/
ModeがRead-onlyと指示されている場合でも、実行前に表示されるCommandと対象Accountは利用者自身でも確認してください。
事前準備
- IBM Bobを利用できること
- IBM Cloud CLIがInstallされていること
- 対象AccountへCLIでLogin済みであること
- Login Userが必要なResourceを参照できるIAM権限を持っていること
IBM Cloud CLIのInstall方法やLogin方法は、利用環境に応じて公式Documentationを確認してください。
Custom Modeを登録する
Raw YAMLをファイルとして保存したら、Bob Settingsの「モード」を開き、ImportアイコンからYAMLを選択します。
登録後、Bob Settingsの「モード」に☁️ IBM Cloud Service Instance Reportが表示されれば準備完了です。
Custom Modeの基本的な作成方法については、Bobの公式Documentationも参照してください。
試してみる
ChatのMode選択から☁️ IBM Cloud Service Instance Reportを選びます。
例えば、次のように自然言語で依頼できます。
東京のInstanceを確認する
Show all service instances in Tokyo.
Resource Groupで絞り込む
Resource GroupがdevelopmentのInstanceを一覧にしてください。
Service Typeで絞り込む
FrankfurtにあるKubernetesのInstanceを一覧にしてください。
日本語のHTML Reportを作成する
日本にあるすべてのService Instanceを調べて、日本語のHTML Reportを作成してください。
Report Languageを指定しなかった場合は英語で作成します。
一覧から一つを選び、詳細を確認する
3番目のInstanceの詳細を表示してください。
同じ名前のInstanceが複数ある場合は、Region、Resource Group、または一覧番号で対象を特定します。
生成されるReportのイメージ
本来はSample Report全体を掲載すると、生成結果をより分かりやすく紹介できます。しかし、Service Instance Reportには、Account内で参照できるすべてのInstance NameやResource Groupなど、実環境の情報が含まれます。
そのため、ここではReport上部のみをScreenshotとして掲載し、Account、Login User、Resource Groupなど一部の情報をMaskしています。
Report内のTopologyも、実際のInstance Nameを使って構成されるため、本記事では掲載していません。
Report全体やTopologyの表示は、ぜひご自身のIBM Cloud環境で試してみてください。最初は、影響範囲を確認しやすいTest環境での利用をお勧めします。
Kubernetesを少し特別扱いしている理由
Kubernetes Serviceを一般的なResource Searchだけで確認すると、Cluster ID、Worker Node、Load Balancerなどが別々のRecordとして見える場合があります。
しかし、利用者がPortalで確認したいのは、多くの場合Cluster名を入口とした情報です。そのため、このModeではResource ControllerとGlobal Searchの情報を使い、可能な範囲で次の項目へ整理します。
- Cluster Name
- Region / Location
- Resource Group
- Health State
- Kubernetes / OpenShift Version
- Worker Count
基本的なCluster一覧ではks Pluginを必須としていません。Worker Pool、個別Worker、Subnet、Storage、Add-onなどの詳細が必要な場合にのみ、Installの必要性と次のCommandを案内します。
ibmcloud plugin install ks
ModeがPluginを自動でInstallすることはありません。
Reportを読む際の注意点
生成されるReportは、実行時点のCLI SessionとLogin Userの権限で参照できた情報をまとめたものです。IAM権限、CLIやAPIのError、Metadataの反映状況、仕様変更などにより、Accountの完全なInventoryにならない可能性があります。
また、ReportにはInstance Name、Resource Group、Region、構成情報など、組織内では機密性を持つ情報が含まれる場合があります。HTML、CSV、JSONを第三者へ共有する前に、内容を確認してください。
本Modeは学習・検証・Workshop向けのSampleであり、公式Support Toolや品質保証されたAssetではありません。生成結果を監査証跡、正式なCMDB、Security Assessment、Compliance判断の唯一の根拠として使用しないでください。
まとめ
今回、IBM CloudのService Instance Inventoryを題材に、BobのCustom Modeを作ってみました。
Custom ModeにTaskの手順だけでなく、認証方法、Read-only境界、Reportの保存先、Kubernetesの整理方法まで定義しておくことで、単発のPromptよりも一貫した流れを作りやすくなりました。
特に効果を感じたのは、次の3点です。
- Service Instanceを入口とする共通のQuery Modelを持てる
- 変更操作を禁止し、CLI SessionとCredentialの扱いを明示できる
- 調査結果を同じ構成のHTML Reportへまとめられる
特定のTaskについて、「何をするか」だけでなく「何をしないか」も含めて定義したい場合に、Custom Modeは便利な仕組みだと感じました。