doca-bare-metal-deployment

DOCA のベアメタルデプロイ

例

• 「起動直後にバイナリが 1 を返して終了します。」 — これは対象範囲内です。 アプリケーションコードを書き換える前に、起動／デバイスのバインド／分離の失敗として扱ってください。
• 「systemd が DOCA アプリを再起動し続けます。」 — ハードウェア上の再起動ループは重大な問題です。Restart=always を有効にする前に、最初の終了原因をデバッグしてください。

手順

以下の読み込み順に従ってください。起動／監視／復旧についてはタスク用の関連ファイルを開き、ランタイムの契約については機能用の関連ファイルを開いてください。関連ファイルをすべて開く必要はありません。

最初に確認する場所： このスキルは、DOCA にリンクされたアプリケーションバイナリをハードウェア上で直接運用するための、このバンドルの中心です。コンテナーも kubelet も静的 Pod マニフェストも使いません。コンテナーを使用しない場合のパスであり、doca-container-deployment/SKILL.md に対応します。ユーザーがビルドした DOCA リンク済みバイナリ（正規のワークフローについては doca-programming-guide/SKILL.md を参照）を持っていて、ホスト上で、または BlueField の Arm コア上で正しく実行する方法を知りたい場合は、タスク用の関連ファイルを開き、## configure から始めてください。ベアメタルのランタイムはどのような構成で、デプロイの契約は何かという質問であれば、機能用の関連ファイルから始めてください。対象システムがコンテナパスとベアメタルパスのどちらなのか、ユーザーがまだ判断できていない場合は、まず doca-setup/SKILL.md で判定してもらい、ベアメタルと確認できた時点でここに戻ってください。

対象ユーザー

このスキルは、DOCA にリンクされたアプリケーションバイナリをビルド済みで、それをハードウェア上で直接実行したい外部の DOCA 開発者および運用者、つまり、すでに次のものを持っている人を対象としています。

• doca-programming-guide ## build に従ってビルドした、DOCA にリンクされたアプリケーションバイナリ。
• 実機の BlueField NIC と、それに接続するホスト（ホスト x86 パス — ホストにインストールされた DOCA が PCIe 経由で BlueField NIC と通信します）、または Arm 側にコンソールか SSH で接続できる BlueField（BlueField Arm ベアメタルパス — DPU の Arm コアに DOCA をインストールし、そこでバイナリを直接実行します）。
• kubelet-standalone で管理されるコンテナー内ではなく、ハードウェア上でそのバイナリを直接実行したいという要望。

対象外は次のとおりです。

• mlx5_* や BlueField OS に貢献するカーネルドライバー開発者。
• DOCA ライブラリの貢献者（その変更はベアメタルデプロイではなく、内部の DOCA ツリーに反映します）。
• BlueField のフリートを管理するフル Kubernetes クラスターの運用者（このバンドルが対象とするのは、単一ホストの kubelet-standalone 構成における doca-container-deployment/SKILL.md です。フリート／本番規模のデプロイはフリートオーケストレーションの対象範囲です。手作業で静的 Pod のループを構築するのではなく、doca-public-knowledge-map ## Deploying DOCA services at scale のオーケストレーション用エントリーポイント（DPF ／ Network Operator ／ Launch Kit）に誘導してください）。
• まだ DOCA をインストールしておらず、ハードウェアもない、購入したばかりのノート PC のユーザー。この場合は doca-setup ## no-install が対象です。

このスキルでは、ベアメタルデプロイの手順と、doca-public-knowledge-map/SKILL.md を介して公開版 DOCA Programming Guide および公開版 BlueField ／ DPU User Manual に記載されたコマンドを引用する際のルールをエージェントに教えます。フラグ名、PCI BDF、NUMA 番号、devlink パス、representor 文字列、systemd の Restart= モード名を記憶だけに頼って作り出すことはしません。

このスキルを読み込むタイミング

ホスト x86 または BlueField Arm の、サポート対象となる 2 つのホストモードのいずれかで、DOCA にリンクされたアプリケーションバイナリをベアメタルに手動でデプロイする場合、または特定のライブラリの API に限定されない、複数の領域に関わるベアメタルの質問をする場合に、このスキルを読み込みます。具体的には、次のような場合です。

• PCIe スロットに BlueField NIC を搭載し、ホストに DOCA をインストールした環境で、ホスト上で DOCA にリンクされたバイナリを初めて起動する場合。
• BlueField OS イメージに従って Arm 側に DOCA をインストールした環境で、BlueField Arm コア上で DOCA にリンクされたバイナリを直接起動する場合（BlueField Arm ベアメタルモード）。
• 起動モードを選ぶ場合（対話型デバッグにはフォアグラウンドでの直接実行、手動で再接続する長時間実行には tmux/screen、再起動後の再開、journald と統合されたログ、および Restart= ポリシーには systemd による監視）。
• DOCA プロセスを適切な PCIe 機能、適切な representor、適切な NUMA ノード、適切な CPU セットにバインドし、アドレスやフラグ名を推測せずに IRQ もそれに合わせて固定する場合。
• cgroup-v2 の cpu／memory／io コントローラー、マルチテナントデプロイ向けのネットワーク名前空間、CPU と NUMA のバインド用の numactl／taskset を使ってテナントごとの分離を設定し、複数の DOCA プロセスが同じ BlueField を共有しても互いの処理を妨げないようにする場合。
• ベアメタルでの起動に問題がある場合の診断（起動しない、起動直後に終了する、実行されるがデバイスを検出できない、デバイスに接続するがワークロードでエラーが発生する、OOM やシグナルによって強制終了される、監視プロセスのもとで再起動を繰り返す、または同居するテナントの影響を受ける）。
• 複数の領域に関わる質問：「tmux と systemd ユニットのどちらで実行すべきか」「ベアメタル上のバイナリを一括処理する前に行うスモークテストのループとは」「BlueField のコンテナー内では動作するバイナリが、Arm 上で直接実行すると動作しない。何が変わったのか」など。

コンテナー経由での同等の操作に関する質問（その場合は doca-container-deployment/SKILL.md を参照）、 Kubernetes クラスター全体の運用（このバンドルの対象外）、 ライブラリ API に関する質問（該当する libs/<library> スキルを参照）、 巨大ページ、IOMMU、pkg-config、devlink モードの切り替えを含む環境準備に関する質問（doca-setup/SKILL.md を使用）、 mlxconfig の書き込みや BFB の再フラッシュなど、ハードウェアの状態を変更する操作（複数の領域に関わるメタポリシーについては doca-hardware-safety/SKILL.md を参照）、 ライブラリをまたぐプログラミングに関する質問（doca-programming-guide/SKILL.md を使用）には、このスキルを読み込まないでください。

このスキルで提供する内容

これは薄いローダーです。実質的な内容は、次の2つの関連ファイルに記載されています。

• capabilities 関連ファイル — DOCA にリンクされたバイナリ向けのベアメタルデプロイ時のランタイム契約です。2つのホストモード（ホスト x86 と BlueField Arm ベアメタル）、3つの起動モード（直接起動、tmux/screen、systemd による監視）、ハードウェアリソースのバインド範囲（PF / VF / representor の列挙、NUMA トポロジーの検出、CPU 固定の根拠、IRQ アフィニティのルール）、テナントごとの分離範囲（cgroup-v2 の cpu / memory / io、ネットワーク名前空間、numactl / taskset）、再起動と復旧のセマンティクス（文書化された systemd の Restart= モード、クラッシュ後の調査、スーパーバイザーによる再起動）、doca-version/SKILL.md が管理する4方向のバージョン一致に対するベアメタル固有のバージョンオーバーレイ、横断的なエラー分類（順に確認する7つのレイヤー）、可観測性の範囲（起動モード別の stdout/stderr の扱い、devlink / sysfs / mlxconfig の query を介したデバイス状態のイントロスペクション、テナントごとのリソース可視性）、および安全ポリシー（doca-hardware-safety/SKILL.md に対するオーバーレイ：バイナリは一括実行の前にスモークテストを行う、ベアメタルプロセスの失敗は重大なリスクを伴う、PCI アドレス、NUMA 番号、representor 名、devlink パス、systemd の Restart= モード名を捏造しない、ワークロードの開始前にテナント分離のプリミティブを確認する）を扱います。
• tasks 関連ファイル — 対象範囲内のベアメタル操作を段階的に進めるワークフローです。configure、build、modify、run（cgroup-v2 / 名前空間 / numactl によるテナントごとのプリミティブを扱う ### isolation サブアンカーを明示）、test、debug、bluefield-lifecycle（BFB のインストール → RShim/TMFIFO → BFB 後の復旧という運用手順。6状態の bluefield-state-classifier サブアンカーを含む）、Command appendix（エージェントが引用できる、公開ドキュメントの出典への相互リンク付きの文書化済みコマンド。コマンドの捏造は禁止）、およびコンテナパス / クラスター / ライブラリ API / 環境準備 / ハードウェア状態の変更 / ライブラリ間の質問をそれぞれの担当スキルへ誘導する Deferred task verbs ブロックが含まれます。（## bluefield-lifecycle から呼び出される変更を伴う書き込み処理の変更適用手順は、引き続き、併せて読み込む doca-hardware-safety/SKILL.md が管理するメタポリシーです。）

このスキルは、次の条件を満たすホストまたは BlueField ターゲットを前提とします。

• DOCA がすでにインストールされ、正常に動作していること（doca-setup ## test に準拠）
• ユーザーが自分でビルドした、DOCA にリンクされたアプリケーションバイナリを持っていること（doca-programming-guide ## build に準拠）
• ユーザーがデバイスの列挙、hugepage の確保、systemd ユニットの書き込み（その起動モードを選択する場合）、NUMA ノードへのプロセスのバインドを行うためのホスト OS の権限を持っていること

DOCA のインストールは対象外です。この手順については doca-setup/SKILL.md を参照してください。バイナリのビルドも対象外です。この手順については doca-programming-guide/SKILL.md を参照してください。

読み込み順

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（ホスト x86 または BlueField Arm 上での、DOCA にリンクされたバイナリのベアメタル起動）かどうかを確認します。（コンテナパス、フルクラスター、ライブラリ API に関する質問は対象外です。）
2. ランタイム契約（2つのホストモード、3つの起動モード、ハードウェアバインド範囲、テナントごとの分離、バージョンオーバーレイ、7層のエラー分類、可観測性の範囲、ベアメタルの安全性オーバーレイ）については、capabilities 関連ファイルを参照してください。
3. 段階的なワークフロー — configure、build（ルーティング用スタブ）、modify（ルーティング用スタブ）、run（### isolation サブアンカーを含む）、test、debug、bluefield-lifecycle（BFB のインストール + RShim/TMFIFO + BFB 後の復旧 + 6状態の bluefield-state-classifier）、さらに Command appendix と Deferred task verbs ブロックについては、tasks 関連ファイルを参照してください。

このスキルが適切に回答できる質問の例

このスキルが意図的に提供しない内容

関連スキル