infrahub-managing-menus

Infrahub Menu Creator

概要

Infrahub のカスタムメニューを作成するための専門的なガイダンスです。 メニューは Web インターフェースの左側のナビゲーションを制御し、スキーマのノードタイプをカスタムの階層に整理します。

プロジェクトのコンテキスト

既存のメニューファイル: !find . -name "*.yml" -path "*/menus/*" 2>/dev/null | head -10

スキーマファイル (利用可能なノードタイプを特定するため): !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

使用する場面

• Infrahub Web UI のナビゲーションメニューを設計するとき
• ノードタイプを論理的なグループと階層に整理するとき
• メニュー項目にアイコンとラベルを追加するとき
• ネストされた子項目を伴うグループヘッダー (クリック不可) を設定するとき
• スキーマノードを自動生成のメニューではなくカスタムメニューを使用するように設定するとき
• 既存のメニューファイルを並べ替え、名前を変更、またはグループ分けし直すとき
• メニュー項目が表示されない、または誤ったグループに入る原因をデバッグするとき

ルールのカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	フォーマット	format-	apiVersion、kind、spec
CRITICAL	プロパティ	item-	name、namespace、label、kind
HIGH	階層	hierarchy-	ネスト、グループヘッダー、data
HIGH	アイコン	icons-	MDI アイコン参照、選択肢
MEDIUM	スキーマ	schema-	include_in_menu、kind リンク
LOW	パターン	patterns-	フラットメニュー、コメント、リンク

このスキルが依存するスキーマ機能

カスタムメニューは自動メニューを置き換えるものではなく、それを拡張するものです。重複を避け UI を安定させるには、スキーマ側で協調する設定が必要です。

重複は 2 か所から発生し、そのうちスキーマ側は 1 か所だけです。自動メニューも出力するノードは、以下に示すように include_in_menu: false で解決します。Infrahub 自体が提供するセクションは、メニューファイル内で parent: により解決します。これについては rules/hierarchy-nesting.md で扱います。

メニュー項目が...	スキーマは...	参照
kind: を介してスキーマノードのリストビューにリンクする	URL が解決されるようにそのノード (またはジェネリック) を定義する — さらに、重複する自動メニューエントリを抑制するために、そのノードに include_in_menu: false を設定する	rules/schema-integration.md
ジェネリック kind を介して 1 つのエントリの下にすべてのサブタイプを表示する	ジェネリックを定義し、関連するすべてのノードをそれから inherit_from させる	../infrahub-managing-schemas/rules/hierarchy-setup.md
自動メニューが有効なときに特定の位置に表示される必要がある	スキーマノードに order_weight を設定する (自動メニューはこれを使用し、カスタムメニューは無視します)	../infrahub-managing-schemas/rules/display-order-weight.md
親ノードのエントリの下にサブタイプをグループ化する	各サブタイプに menu_placement: <FullKind> を設定し、自動メニュー側がカスタムメニューと一貫してグループ化されるようにする	../infrahub-managing-schemas/rules/display-menu-placement.md

メニューファイルから参照するすべてのノードについて include_in_menu を監査してください。これによって防止されるサイドバーの重複は、ユーザーにはカスタムメニューが「壊れている」ように見えますが、修正すべきはスキーマ側です。

メニューファイルの基本

---
apiVersion: infrahub.app/v1
kind: Menu
spec:
  data:
    - namespace: Dcim
      name: DeviceMenu
      label: "Devices"
      icon: "mdi:server"
      kind: DcimDevice        # Links to schema node list view

apiVersion、kind: Menu、spec.data は常に必須です。各メニュー項目には name と namespace が必要です。

ワークフロー

メニューを作成する際は、次の手順に従ってください。

1. 要件を収集する — どのスキーマノードが存在するか、 それらをどのようにグループ化すべきか、ユーザーが フラットなナビゲーションと階層的なナビゲーションの どちらを希望するかを尋ねます。

2. 関連するルールを読む — 必要な YAML 構造については rules/format-structure.md を、アイテムのフィールドについては rules/item-properties.md を、適切な MDI アイコンを選ぶために rules/icons-reference.md を読みます。アイテムを配置する前に、 フラットなメニューも含めて rules/hierarchy-nesting.md を 読んでください。Infrahub にはすでに IPAM、 Object Management、Branches などが同梱されており、 それらのいずれかに属するものは再度宣言するのではなく parent: で紐付けます。

3. メニュー YAML を生成する — $schema コメントと apiVersion/kind/spec 構造から始めます。手順 2 の ルールを適用します。

4. 登録とスキーマのガイダンスを追加する — 出力する すべてのメニューファイルに、以下を含める必要があります。

   • .infrahub.yml の menus: キーの下にファイルを登録する方法を 示す YAML コメントブロック (rules/format-structure.md を参照)
   • カスタムメニューに表示されるすべてのスキーマノードに include_in_menu: false を設定して、サイドバーの 重複エントリを防ぐことを推奨する YAML コメントブロック (rules/schema-integration.md を参照)

   これらはファイルの先頭、--- ドキュメント区切り文字の 前にコメントとして含めてください。これにより、ユーザーは メニュー定義と一緒にガイダンスを確認できます。

参考資料

• examples.md -- コピーして適応できる 4 つの実践的なメニュー階層 (フラット、グループ化、 汎用リンク、完全なマルチドメイン)
• infrahub-yml-reference.md -- .infrahub.yml プロジェクト設定
• common/rules/ -- すべてのスキルに適用される共有ルール (git 統合、キャッシュの注意点)
• ../infrahub-common/rules/workflow-information-priority.md -- スキルコンテンツを優先すること。真のギャップ (例: ノードの削除) がある場合に docs.infrahub.app を 参照する方法
• managing-schemas -- メニューがリンクするスキーマノードの種類
• rules/ -- カテゴリプレフィックス別に整理された個別のルール