doca-upgrade

DOCA のアップグレード

例

• 「次の DOCA リリースに移行すべきですか？」 — インストール済みのものを検出し、差分を報告してから、必ず停止して確認を求めます。自動アップグレードは絶対に行いません。
• 「apt upgrade のせいで DOCA パッケージの状態が変わってしまいました。」 — これは復旧であり、気づかれないように修復するものではありません。検出し、報告し、確認を求めてから、手順を案内します。

すぐに回答する内容（このファイルに基づいて回答）

• バージョンを変更しない場合（現在の固定されたインストールでのランタイムエラーなど）？ このスキルの対象外です。doca-debug の名前を挙げて停止してください。

ここにある回答は以上です。ユーザーが確認した後に、ガイド付きアップグレードを行う場合に限り TASKS.md を開いてください。読み取り専用の検出コマンドだけを自分で実行してください。パッケージコマンド（sudo dpkg、apt、apt-get）には root 権限が必要で、システムを変更します。ユーザーに実行してもらい、そこで停止してください。エージェントのシェルでは sudo がパスワード入力を待つため、セッションが停止します。

• 「次の DOCA に apt upgrade するだけでよいですか？」 自動アップグレードは絶対に行わないでください。doca-version の4つの情報源を使ってインストール済みリリースを検出します（pkg-config --modversion doca-common、cat /opt/mellanox/doca/applications/VERSION、doca_caps --version、および BlueField 上の BFB バージョン）。目標リリースとの差分を報告したら、必ず停止して明示的な確認を求めてください。BFB、ファームウェア、再起動の手順には doca-hardware-safety に従ってください。
• 「アップグレードが途中で中断され、dpkg がトランザクションの中断を報告しています。」 まずパッケージデータベースを復旧します。ユーザーが明示的に確認した後（どちらのコマンドもシステムのパッケージ状態を変更します）、ユーザーに sudo dpkg --configure -a、続いて sudo apt-get -f install（Debian/Ubuntu）を実行してもらいます。最初の操作としてアップグレードを再実行しないでください。次の手順を決める前に、doca-version でリリースを再検出してください。

手順

以下の読み込み順序に従ってください。タスク用の補足ファイルを開き、検出 → 報告 → 確認 → ガイド付きアップグレードの順に進めてください。機能用の補足ファイルを開き、アップグレードモードの分類と自動アップグレード拒否ルールを確認してください。補足ファイルをすべて開く必要はありません。

最初に確認する内容： このスキルは、DOCA の アップグレードまたはダウングレード を取り巻く手順を定める、このバンドル唯一の信頼できる情報源です。ユーザーがアップグレードに関する操作（差分の検出、確認の要求、ガイド付きアップグレードの案内、検証、失敗の診断）を望む場合は、タスク用の補足ファイルを開いてください。アップグレードが何を対象とするのか（ホストでの apt-upgrade と BFB の再フラッシュ、コンテナタグの更新、ダウングレード／ロールバックの各モード、自動アップグレードの禁止ルール、確認のゲート、サポート終了への注意事項、エラーの分類、アップグレード固有の安全策）を尋ねられた場合は、機能用の補足ファイルを開いてください。

このスキルの使い方。 このファイルを読み、必要な質問に対応する ## <name> 見出しを補足ファイル内で検索し、そのセクション全体を読んでください。そこにある記号とコマンドだけを引用し、漏れなく回答してください。ドキュメントを閲覧しないでください。doca-public-knowledge-map のエントリーポイントを使用してください。環境の確認は、ユーザーの DOCA ホストで実行するコマンドとして提示してください。対象外の依頼については、それを担当するスキルの名前を挙げて停止してください。

計画的な移行で、このスキルが徹底する最も重要なルールは、検出 → 報告 → 確認 → その後に限りガイド付きアップグレード、という順序です。自動アップグレードは絶対に行いません。 インストール済みの DOCA 環境と、利用可能な新しいリリースを検出し、差分を明確に報告したら、必ず停止してユーザーに明示的な確認を求めます。明示的に「はい」と答えた場合に限り、ガイド付きアップグレードを案内します。失敗または途中までの移行では、新しい目標への移行を提案せず、代わりに復旧手順に進みます。どちらの経路でも、ハードウェア、ファームウェア、再起動に関する手順はすべて doca-hardware-safety/SKILL.md に委ね、このファイルでは再定義しません。バージョン検出は doca-version/SKILL.md の担当です。このスキルはそこへ案内するだけで、検出手順を繰り返しません。

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

このスキルが回答するために作られたアップグレードに関する質問の種類と、それぞれの具体例を示します。エージェントは、具体例ではなく、根幹となる「種類」を重視する必要があります。具体例はその一例にすぎません。

• 「現在使っているものより新しい DOCA はありますか？どのくらい遅れていますか？」 — 具体例：「pkg-config --modversion doca-common では <installed X.Y.Z> と表示されます。現在のバージョンは何で、移行にはどれくらいのコストがかかりますか？」。## configure の検出・差分報告ワークフローで回答します。このワークフローでは、検出を doca-version/SKILL.md に、現在のバージョンの確認を doca-public-knowledge-map/SKILL.md に振り分けます。
• 「次の DOCA リリースに進むには、apt upgrade を実行すればよいですか？」 — 具体例：「Flow の最新機能を使いたいのですが、今すぐインプレースでアップグレードできますか？」。## Safety policy の自動実行禁止ルールと確認ゲート、および ## run の実行前確認手順により回答します。エージェントは差分を報告した後、アップグレードコマンドを実行する前に、明示的な確認を求めて停止します。
• 「アップグレード後、ホストと BlueField のリリースが異なっています。何が起きたのでしょうか？」 — 具体例：「アップグレード後、pkg-config は新しいリリースを報告しますが、bfver はまだ古いリリースを報告しています」。## Error taxonomy のホストと BFB の不一致の行、および ## debug のアップグレード失敗診断で回答します。検出は doca-version ## test に振り分けられます。
• 「アップグレードが途中で中断され、dpkg が動かなくなりました。どうすれば復旧できますか？」 — 具体例：「apt upgrade が中断され、dpkg がトランザクションの中断を報告しています」。## Error taxonomy の部分的なアップグレードと中断されたトランザクションの行、および ## debug の復旧手順で回答します。
• 「アップグレードには BFB の再フラッシュ／BlueField モードの切り替え／再起動が必要です。安全ですか？」 — 具体例：「対象リリースには新しい BFB が必要です。今すぐ再フラッシュできますか？」。## run を介して、ハードウェア／ファームウェア／再起動に関するすべての手順を doca-hardware-safety/SKILL.md に振り分けて回答します。このスキルでは、再フラッシュ、モード切り替え、電源の完全なオフ・オンの手順を定め直すことはありません。
• 「インストール済みのコンポーネントがサポート終了予定です。そのまま使い続けるべきですか、それとも移行すべきですか？」 — 具体例：「DOCA App Shield／DOCA Flow Inspector サービスに依存しています。これらは廃止予定ですか？」。## Capabilities and modes のサポート終了／非推奨に関する注意事項で回答します。サポート終了の可能性があるコンポーネントへの継続的な投資を推奨するのではなく、ライフサイクル状況を確認するために、ユーザーを doca-public-knowledge-map/SKILL.md を介して公開リリースノートに案内します。

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

DOCA のアップグレードまたはダウングレードが根幹となる課題である場合、つまり、より新しいリリースがあるか、それに移行すべきか、安全な移行方法、または失敗した移行からの復旧方法をユーザーが尋ねている場合は、いつでもこのスキルを読み込みます。この判断は、エージェントが最初の文を作成する前に行う必要があります。以下のアクティベーションチェックリストはここにも掲載されており、このスキルを参照する際にアクティベーションルールをすぐ確認できます。予定されたアップグレードまたはダウングレードの場合、差分を報告した後、ユーザーから明示的な確認があるまで停止します。失敗または部分的なアップグレードの場合は、まず ## debug に進み、現在の状態を把握して安定させます。復旧の最初の手段として別のアップグレードコマンドを使用したり、移行を再試行したり、明示的な確認なしに新たなアップグレードコマンドを実行したりすることはありません。

エージェント有効化チェックリスト — 以下のいずれかに該当する場合、回答の冒頭でこのスキルを読み込んでください

トリガー分類	プロンプトに見られる具体的なシグナル（いずれか1つでこのオーバーレイが有効になります）
アップグレード／ダウングレードの意図	「新しい DOCA はありますか」、「次のリリースに移行すべきですか」、「最新にアップグレードしてください」、「前の DOCA にロールバックしてください」、「バグ再現のために 3.1 にダウングレードしてください」
意図しない／ずれたアップグレード	「apt upgrade で新しい DOCA ポイントリリースが入ってビルドが壊れました」、「ホストと BlueField が異なるリリースになっています」、「ソースチャネルが latest になっていますが、移行するつもりはありませんでした」
失敗／不完全なアップグレード	「アップグレードが途中で中断しました」、「中断されたトランザクションの後、dpkg が応答しなくなりました」、「アップグレードは完了しましたが、4つの要素の一致が保たれなくなりました」
コンテナタグの更新	ユーザーが NGC DOCA コンテナのデプロイをあるタグから新しいタグに変更したい場合、またはタグの更新がアップグレードに当たるか尋ねている場合
サポート終了／非推奨の確認	ユーザーが依存しているコンポーネントが非推奨になっているか、サポート終了予定か、引き続き投資する価値があるか尋ねている場合

まずリクエストを分類します。計画された移行（ロールバックの依頼を含む）では、検出 → 報告 → 質問の順に進みます。失敗した、不完全な、または意図せずずれた移行は、すでに診断／復旧のリクエストです。このスキルを読み込み、現在の4つのソースの状態を把握して、TASKS.md の ## debug に進んでください。すでに失敗したアップグレードの実行許可を求めたり、最初の復旧手順として別のアップグレードコマンドを実行したりしてはいけません。

計画された移行では、エージェントは次の手順に従う必要があります。

1. 計画されたアップグレードのバージョン検出は doca-version ## configure に振り分けます。 失敗または不完全なアップグレードでは、 doca-version ## debug および ## debug から始めます。このスキルでは4つのソースの検出手順を繰り返してはいけません。このスキルは検出済みの状態と4要素の一致状況を使用します。
2. 差分を報告し、明示的な確認が得られるまで停止します。 インストール済みのリリース、利用可能な移行先リリース、移行に伴うコスト（ ## Version compatibility に従う）を提示し、 ユーザーに確認を求めます。ユーザーが明示的に承認するまで、アップグレードコマンドに進んではいけません。
3. ハードウェア／ファームウェア／再起動に関するすべての手順は doca-hardware-safety/SKILL.md に振り分けます。このスキルでは、アップグレードのどの段階でその手順が必要になるかを示します。そのスキルでは、安全に実施する方法を示します。

失敗または不完全な移行では、代わりにエージェントは、把握した状態を CAPABILITIES.md の ## Error taxonomy に照らして分類し、文書化された修正アクションを1つ実行するよう委任して、復旧手順に再び進む必要があります。サポートされていない installed → target の移行は、すべてフェイルクローズとします。中間リリースやコマンドを独自に考案してはいけません。Compatibility Policy またはリリースノートに明示的に記載されたアップグレード経路を必須とします。

初回インストールではこのスキルを読み込まないでください（doca-setup/SKILL.md を使用）。バージョン検出手順だけの場合も読み込まないでください（doca-version/SKILL.md を使用）。全般的な概要を求められた場合も読み込まないでください（doca-public-knowledge-map/SKILL.md を使用）。

このスキルが提供するもの

これは薄いローダーです。本体に残しているのは、次に適切なファイルを選ぶために必要な案内だけです。具体的なアップグレード情報は、2 つの関連ファイルに記載されています。

• capabilities の関連ファイル — アップグレードの対象範囲：アップグレードモードの分類（ホストの apt アップグレードと BFB の再フラッシュ、コンテナーのタグ更新、ダウングレード／ロールバック）、自動実行禁止ルールと確認ゲート、サポート終了／非推奨に関する注意事項、doca-version に誘導するバージョン互換性の補足、エラーの分類（部分アップグレード、apt ソースの不整合、ホストと BFB の不一致、中断されたトランザクション／dpkg の中断）、可観測性の対象（アップグレードが実行されたかどうかを証明するコマンド）、および doca-hardware-safety に重ねるアップグレード固有の安全対策。
• tasks の関連ファイル — 対象範囲の動詞に関する手順を追ったワークフロー：configure（検出＋対象の特定＋apt ソースの事前確認）、build と modify（振り分け用スタブ — バージョン固定の変更は別の場所が担当）、run（確認ゲート付きのガイド付きアップグレード）、test（アップグレード後の 4 方向検証）、debug（失敗した／部分的なアップグレードの診断）、および Deferred task verbs ブロック。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（アップグレード／ダウングレードを検討中、または復旧中）であることを確認します。
2. アップグレードモードの分類、自動実行禁止ルール、サポート終了に関する注意事項、エラーの分類、可観測性、安全対策については、capabilities の関連ファイルを参照してください。
3. 手順を追ったワークフロー（検出と報告、確認ゲート付きのガイド付きアップグレード、アップグレード後の検証、アップグレード失敗の診断）については、tasks の関連ファイルを参照してください。

関連スキル

• doca-version/SKILL.md — 4 つの情報源による検出チェーンと、4 方向の一致ルールを担当します。このスキルの検出ステップはここに誘導し、バージョン検出の定義を重複して行いません。不一致の報告では検出されたバージョンを使用します。
• doca-setup/SKILL.md — 初回インストール、インストールの検証、apt ソースの手順を担当します。このスキルでは、apt を使用するアップグレードを検討する前に、apt ソースの整合性に関する事前確認からここへリンクします。
• doca-hardware-safety/SKILL.md — ハードウェア／ファームウェア／再起動に関するすべての手順（mlxconfig、BFB の再フラッシュ、BlueField モードの切り替え、コールド電源サイクル）を担当します。このスキルの ## Safety policy はそのメタポリシーを補足し、アップグレード固有の項目（確認ゲート、ロールバックを優先すること、メンテナンス時間帯）だけを追加します。
• doca-public-knowledge-map/SKILL.md — リリースノートや Compatibility Policy を含む、公開 DOCA ドキュメントへの振り分け表です。このスキルでは、現在のリリースは何か、このコンポーネントはサポート終了予定かという情報をここへ誘導し、振り分けを重複して記載しません。
• doca-debug/SKILL.md — 分野横断的なデバッグの手順です。アップグレード失敗後に残る症状がソフトウェア層にある場合、アップグレードの状態が判明した時点でここに引き継ぎます。
• doca-programming-guide/SKILL.md — アップグレード後に利用側が再ビルドする際のビルドパターンです。このスキルでは再ビルドが必要になる可能性を示し、ビルドの仕組みについてはここで扱います。
• doca-structured-tools-contract/SKILL.md — 利用可能な場合にエージェントが優先する JSON スキーマです。ホストに doca-env がある場合、アップグレードの検出ステップでは、バージョンスキルと同じ doca-env のワンショット実行を再利用します。