Azure CLIからクラスター ランタイムをアップグレードする

この記事では、Operator Nexus クラスターのランタイム アップグレードを実行する方法について説明します。

[前提条件]

1. 適切な CLI 拡張機能の最新バージョンをインストールします。
2. Azure Operator Nexusネットワークファブリック（NF）およびネットワーククラウド（NC）のCLI拡張コマンドを実行するためのサブスクリプションアクセス。
3. 次の情報を収集します。
   • サブスクリプション ID (SUBSCRIPTION)
   • クラスター名 (CLUSTER)
   • リソース グループ (CLUSTER_RG)
4. クラスターの詳細な状態は Runningする必要があります。
5. クラスター間マネージャーの接続は Connectedする必要があります。
6. Azure前提条件 (Log Analytics ワークスペース、Storage アカウント、Key Vault) を検証する必要があります。 これらのリソースは、アップグレードを開始する前にチェックされます。 「クラスターマネージド ID」と「ユーザー指定のリソース」を参照してください。
7. クラスター > ワークロード > コンピューティング サーバーで
   • アップグレード前のコントロール プレーン ノードの正常性要件は次のとおりです。
     • 予備のコントロール プレーン ノードが存在しない場合は、すべてのコントロール プレーン ノードが正常である必要があります。電源状態 On、Cordon 状態 Uncordoned、準備完了状態 Yes、および機能低下 No。
     • スペア・コントロール・プレーン・ノードが存在する場合は、予備ノードのみが電源状態 Off、準備完了状態 No、および機能低下 No状態にすることができます。 他のすべてのコントロール プレーン ノードは正常である必要があります。電源状態 On、Cordon 状態 Uncordoned、準備完了状態 Yes、および機能低下 No。

     注

     予備のコントロール プレーン マシンが以前にプロビジョニング プロセスを経た場合は、Cordon 状態 Cordonedと予想されます。 そうでない場合は、UncordonedCordon 状態であるはずです。

   • 管理プレーンのサーバーは、奇数番号ラックと偶数番号ラックの2つのグループに分割されます。 各グループでは、少なくとも 50% を超えるサーバーが正常である必要があります。電源状態 On、Cordon 状態 Uncordoned、準備完了状態 Yes、および機能低下 No。
     • 両方の管理プレーン グループで、少なくとも 75% の管理マシンが正常である必要があります。
   • コンピューティング プレーン のサーバー番号は、個々のクラスター ランタイムのしきい値の設定によって異なります。 お客様は、設定に基づいて最小数を確定し、電力状態 On、Cordon 状態 Uncordoned、準備完了状態 Yes、そして劣化状態 Noを確認してください。
8. [クラスター > マネージド リソース グループ] で、リソース グループ ページに移動するグループ名を選択します。
   • リソース グループで、Kubernetes - Azure Arc を検索して、Azure Arc情報を識別して選択します。 状態は Connectedする必要があります。
     • Azure Arcページで、[設定] > 拡張機能を選択します。
       • nc-platform-extension は状態 Succeededにする必要があります。
       • nc-platform-runtime-extension は状態 Succeededにする必要があります。

現在のランタイム バージョンの確認

アップグレード前に現在のクラスター ランタイムのバージョンを確認する: 現在のクラスター ランタイムのバージョンを確認する方法を参照してください。

使用可能なランタイム バージョンの検索

Azure portal を使用して

使用可能なアップグレード可能なランタイム バージョンを見つけるには、Azure portal内のターゲット クラスターに移動します。 クラスターの概要ウィンドウで、[ 使用可能なアップグレード バージョン ] タブに移動します。

利用可能なアップグレード バージョン タブから、アップグレードに使用できるさまざまなクラスター バージョンを確認できます。 一覧からターゲット ランタイム バージョンを選択し、クラスターのアップグレードに進みます。

Azure CLI経由

使用可能なアップグレードは、Azure CLIを使用して取得できます。

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A8 availableUpgradeVersions

出力で、availableUpgradeVersions プロパティを見つけて、targetClusterVersion フィールドを確認できます。

  "availableUpgradeVersions": [
    {
      "controlImpact": "True",
      "expectedDuration": "Upgrades may take up to 4 hours + 2 hours per rack",
      "impactDescription": "Workloads will be disrupted during rack-by-rack upgrade",
      "supportExpiryDate": "2023-07-31",
      "targetClusterVersion": "3.3.0",
      "workloadImpact": "True"
    }
  ],

使用可能なクラスター アップグレードがない場合、一覧は空です。

クラスターを使用してランタイム アップグレードのコンピューティングしきい値パラメーターを構成する updateStrategy

次のAzure CLI コマンドを使用して、ランタイム アップグレードのコンピューティングしきい値パラメーターを構成します。

az networkcloud cluster update \
--name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--update-strategy strategy-type="<strategyType>" threshold-type="<thresholdType>" \
threshold-value="<thresholdValue>" max-unavailable="<maxNodesOffline>" \
wait-time-minutes="<waitTimeBetweenRacks>"

[Required parameters]\(必須のパラメーター\):

• strategy-type: 更新戦略を定義します。 使用される設定は、 Rack (ラックごとの) または PauseAfterRack (各ラックが開始される前にユーザーに対して一時停止) です。 既定値は Rack です。 PauseAfterRack戦略を使用してクラスター ランタイムのアップグレードを実行するには、「PauseAfterRack 戦略を使用したクラスター ランタイムのアップグレード」で説明されている手順に従います。
• threshold-type: 戦略で定義されている単位で適用される、しきい値の評価方法を決定します。 使用される設定は、 PercentSuccess または CountSuccessです。 既定値は PercentSuccess です。
• threshold-value: 更新を評価するために使われる数値のしきい値。 既定値は 80 です。

省略可能なパラメーター:

• max-unavailable: オフラインにできるワーカー ノード (つまり、一度にアップグレードされるラック) の最大数。 既定値は 32767 です。
• wait-time-minutes: ラックを更新する前の遅延または待機期間。 既定値は 15 です。

PercentSuccess しきい値の種類に基づいたアップグレード動作

次の例は、成功率が 60%、一時停止が 1 分間の Rack-by-Rack 戦略を使用しているお客様を対象にしています。

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" \
threshold-value=60 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

更新を確認します。

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

この例では、ラック内のマシンの 60% が正常にアップグレードされると、システムはしきい値が満たされたと見なし、次のラックのアップグレードに進み、現在のラック内の残りのマシンをプロビジョニングし続けます。 しきい値が満たされていない場合 (つまり、ラック内のマシンの% が 60 台未満でアップグレードでき、代わりに失敗した場合、クラスターのアップグレードは一時停止されます。 アップグレードが一時停止されると、その理由を説明する詳細なステータス メッセージがクラスターに表示されます。 その時点で、ラック内の問題のあるマシンを修復し、アップグレードを再開して完了するには、クラスターの更新バージョンの続行操作をトリガーする必要があります。

Azure portalを使用してアップグレードの状態を表示するには、対象のクラスター リソースに移動します。 クラスターの [概要 ] 画面では、詳細な状態が詳細なステータス メッセージと共に表示されます。

detailedStatus が Updating に設定され、detailedStatusMessage にアップグレードの進行状況が示される場合、クラスターのアップグレードは進行中です。 detailedStatusMessage に表示されるアップグレードの進行状況の例としては、Waiting for control plane upgrade to complete...、Waiting for nodepool "<rack-id>" to finish upgrading... などがあります。

detailedStatus が Running に設定され、detailedStatusMessage にメッセージ Cluster is up and running が表示されると、クラスターのアップグレードは完了します

詳細なステータス メッセージにアップグレードが一時停止されていることが示されている場合、メッセージは次のようになります。 Cluster is deployed but the upgrade has been paused. Machines in rack "<rack-id>" are unhealthy. Fix the machines and perform cluster continue-update-version action to finish the upgrade

ランタイムのアップグレードを再開するには、次の az networkcloud cli コマンドを実行します。

az networkcloud cluster continue-update-version --cluster-name "<CLUSTER>" \
--resource-group="<CLUSTER_RG>" \
--subscription="<SUBSCRIPTION>" \
--safeguard-mode <SAFEGUARD_MODE>

省略可能なパラメーター:

• --safeguard-mode: continue-update-version 操作中にセーフガードを適用する方法を指定します。 Allを使用して、すべての事前操作検証チェックを実行します。 Noneを使用して、問題を検出したときにアップグレードをブロックするセーフガードをバイパスします。 既定値は All です。

CountSuccess しきい値の種類に基づくアップグレード動作

次の例は、ラックごとに 10 ノードのしきい値の種類 CountSuccess と 1 分間の一時停止を使用するラックごとの戦略を使用しているお客様を対象にしています。

az networkcloud cluster update --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" \
threshold-value=10 wait-time-minutes=1 \
--subscription "<SUBSCRIPTION>"

更新を確認します。

az networkcloud cluster show --name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" | grep -A5 updateStrategy

  "updateStrategy": {
    "maxUnavailable": 32767,
      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

この例では、少なくとも 10 個のノードが正常にアップグレードされた場合、アップグレードは次のラックに進み、現在のラックに残っているマシンは引き続きプロビジョニングされます。 ラック内の少なくとも 10 台のマシンのアップグレードに失敗した場合、クラスターのアップグレードは一時停止します。 この場合、アップグレードを再開して完了するには、更新バージョンの続行アクションを実行する前に、必要なハードウェアを修復する必要があります。

ベアメタル マシンに関する問題のトラブルシューティングについては、「Azure Operator Nexus サーバーの問題トラブルシューティング」を参照してください。

クラスター ランタイムのアップグレードをブロックできる検証

クラスター ランタイム アップグレードをトリガーすると、クラスター ベア メタル マシンでのランタイム アップグレードが開始される前に、一連のアップグレード前検証が実行されます。 これらの検証により、クラスターの現在の状態を考えると、ランタイムのアップグレードが成功することが確認されます。 詳細については、「 クラスター ランタイム アップグレードのプレフライト検証」を参照してください。

CLI を使用してクラスター ランタイムをアップグレードする

クラスター ランタイムのバージョンをアップグレードするには、次の Azure CLI コマンドを使用します。

az networkcloud cluster update-version\
--cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>" \
--target-cluster-version "<versionNumber>" \
--safeguard-mode "<SAFEGUARD_MODE>"

[Required parameters]\(必須のパラメーター\):

• --target-cluster-version: 更新中にクラスターに適用するバージョン。

省略可能なパラメーター:

• --safeguard-mode: 更新バージョンの操作中にセーフガードを適用する方法を指定します。 Allを使用して、すべての事前操作検証チェックを実行します。 Noneを使用して、問題を検出したときにアップグレードをブロックするセーフガードをバイパスします。 既定値は All です。

このコマンドは、指定されたクラスターのランタイム アップグレード プロセスを開始します。 通常、コマンド自体は約 5 分以内に完了しますが、検証が成功した後にのみアップグレード プロセスが開始されます。 実際のランタイム アップグレードはバックグラウンドで引き続き実行され、ラックごとにノード をアップグレードし、新しい OS バージョンをインストールするため、完了までに数時間かかることがあります。

開始手順の詳細な状態と診断情報は、クラスター (Operator Nexus) リソースの JSON View のAzure portalで確認できます。 API バージョン updateVersion 以降を使用する場合は、properties.actionStates フィールドの2025-07-01-previewエントリに次の情報が含まれます。

• アクションの開始時刻と終了時刻。
• 現在の状態 (Succeeded、 Failed、または InProgress)。
• 現在の状態に関連付けられている追加のコンテキストまたはエラー メッセージ。
• Azure アクティビティ ログにも示すように、元の cluster update-version 操作の関連付け ID。
• 個々のステップとその状態の順序付きリスト ( Validate Cluster conditions and upgrade versions、 Initiate Platform Runtime Extension updateなど)。

クラスター (Operator Nexus) リソースの JSON View 出力例:

{
  "properties": {
    "actionStates": [
      {
        "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "status": "Completed",
        "actionType": "Microsoft.NetworkCloud/clusters/updateVersion",
        "endTime": "2025-08-01T03:46:13Z",
        "message": "Cluster upgrade to 4.6.0 successfully initiated - monitor progress via cluster detailed status",
        "startTime": "2025-08-01T03:42:08Z",
        "stepStates": [
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:42:08Z",
            "message": "Cluster validation and version checks passed",
            "startTime": "2025-08-01T03:42:08Z",
            "stepName": "Validate Cluster conditions and upgrade versions"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension deployment initiated",
            "startTime": "2025-08-01T03:42:39Z",
            "stepName": "Initiate Platform Runtime Extension update"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:11Z",
            "message": "Platform Runtime Extension installation completed",
            "startTime": "2025-08-01T03:46:11Z",
            "stepName": "Monitor Platform Runtime Extension readiness"
          },
          {
            "status": "Completed",
            "endTime": "2025-08-01T03:46:13Z",
            "message": "Platform Cluster version updated successfully",
            "startTime": "2025-08-01T03:46:13Z",
            "stepName": "Update Platform Cluster version specification"
          }
        ]
      }
    ]
  }
}

このコマンドが完了すると、完全なランタイム アップグレード プロセスが開始されます。 クラスター内のラックの数と各ラック内のワーカー ノードの数によっては、このプロセスが完了するまでに数時間かかることがあります。

• アップグレードでは、まずコントロールプレーン ノードがアップグレードされ、次に管理ノードがアップグレードされ、その後ワーカー ノードがラックごとに順番にアップグレードされます。
• 管理サーバーは 2 つのグループに分離され、個別にアップグレードされます。 この方法により、管理サーバー上で実行されているコンポーネントは、アフィニティ ルールを適用することで、実行時のアップグレード中に回復性を確保できます。
• クラウド サービス ネットワーク (CSN) も、各管理グループに 1 つのインスタンスを配置することで、この機能を使用します。
• , この機能には顧客の関与がありません。 ただし、グループを識別するために管理ノードに他のラベルが表示される場合があります。

アップグレードは、ワーカー ノード ラックのクラスターの updateStrategy によって構成されたしきい値が満たされ、各グループ内の少なくとも 50% の管理ノードが正常にアップグレードされると、完了したと見なされます。 ワークロードは、ラック内のワーカー ノードのアップグレード中に影響を受ける可能性がありますが、他のすべてのラックのワークロードには影響しません。 この実装設計を参考にしてワークロードの配置を検討することをお勧めします。

クラスターの詳細な状態を使用して進行状況を監視します。これは、Azure ポータルまたはAzure CLIから入手できます。

Azure CLIを使用してアップグレードの状態を表示するには、az networkcloud cluster showを使用します。

az networkcloud cluster show --cluster-name "<CLUSTER>" \
--resource-group "<CLUSTER_RG>" \
--subscription "<SUBSCRIPTION>"

出力には、ターゲット クラスターの情報と、その詳細な状態と詳細な状態メッセージが含まれます。 アップグレードの進行状況に関する詳細な分析情報については、各ラック内の個々のノードの状態を確認できます。 例については、 BareMetal マシンの役割のリファレンス セクションを参照してください。

Azure ポータルでアップグレードの状態を表示するには、対象のクラスター リソースに移動します。 クラスターの [概要 ] 画面では、詳細な状態と詳細なステータス メッセージを表示できます。

クラスターのアップグレードは、 detailedStatus が Updating に設定され、アップグレードの進行状況 detailedStatusMessage 表示されるときに進行中です。 detailedStatusMessageに示されているアップグレードの進行状況の例としては、Waiting for control plane upgrade to complete...とWaiting for nodepool "<rack-id>" to finish upgrading...があります。

クラスターのアップグレードは、detailedStatusがRunningに設定され、detailedStatusMessageCluster is up and running表示されると完了します。

detailedStatusがUpdatingに設定されている場合、クラスターのアップグレードは一時停止され、アップグレードが一時停止した原因またはコンポーネントdetailedStatusMessage表示されます。

クラスター ランタイムのアップグレードの一時停止

アップグレードは、次のいずれかが発生すると一時停止します。

1. すべてのコントロールプレーン マシンは正常にアップグレードできず、プロビジョニングもされておらず、準備もできていません。
2. 管理プレーングループ内の 50% を超えるマシンはアップグレードできず、プロビジョニングもされておらず、準備もできていません。 管理プレーンのサーバーは、奇数番号ラックと偶数番号ラックの2つのグループに分割されます。
3. しきい値ごとに構成されたコンピューティング ノードまたはワーカー ノード マシンはアップグレードできません。また、プロビジョニングも準備もできません。

クラスターの詳細なステータス メッセージを確認して、アップグレードが一時停止状態に入った原因となったコンポーネントを特定します。 次の例は、各コンポーネントの詳細なステータス メッセージを示しています。

コントロール プレーン (KCP) エラーの詳細なステータス メッセージ

• "クラスターはデプロイされていますが、アップグレードは一時停止されています。 capiCluster <clusterName> が異常であるため、コントロール プレーンのアップグレードに失敗しました。 MachineHealthCheck は、クォーラムを回復するために、正常でない KCP マシンを管理プレーン マシンに置き換えている可能性があります。 修復が完了するまで待ってから、引き続き update-version アクションを実行してアップグレードを完了します。"

コンピュートまたは管理プレーン グループ障害の詳細ステータス メッセージ

• "クラスターはデプロイされていますが、アップグレードは一時停止されています。 ラック "<rack-id>" 内のマシンは異常です。 マシンを修正し、クラスターの continue-update-version アクションを実行してアップグレードを完了します。"

影響を受けるコンポーネント (コントロール プレーン、管理、またはコンピューティング) が特定されたら、次の操作を行います。

手順 1: 影響を受けるコンポーネントの個々のベア メタル マシンの状態を確認します。

例については、 BareMetal マシンの役割のリファレンス セクションを参照してください。

影響を受けるコンポーネントのベア メタル マシンを特定したら、各マシンの状態を確認し、その状態に基づいて次のアクションを実行します。

手順 2: BMM のアクション状態ログを確認します。

BMM のアクション状態ログを確認するには、BMM リソース >Operations>Action Log に移動します。

問題が解決し、Baremetal マシンがプロビジョニングされ、準備ができたら、クラスター continue-update-version アクションを実行してアップグレードを再開し、完了します。

az networkcloud cluster continue-update-version \
-g <CLUSTER_RG> \
-n <CLUSTER_NAME> \
--subscription <CUSTOMER_SUB_ID> \
--safeguard-mode <SAFEGUARD_MODE>

省略可能なパラメーター:

• --safeguard-mode: continue-update-version 操作中にセーフガードを適用する方法を指定します。 Allを使用して、すべての事前操作検証チェックを実行します。 Noneを使用して、問題を検出したときにアップグレードをブロックするセーフガードをバイパスします。 既定値は All です。

よく寄せられる質問

クラスターアップグレードの停止または中断の識別

実行時のアップグレード中、アップグレード プロセスで手動による介入なしにアップグレードを続行できないと判断されると、クラスターは一時停止状態になります。 ただし、詳細ステータスではアップグレードが進行中と表示されたままであっても、アップグレード プロセスが先に進まなくなることがあります。 ランタイムのアップグレードが正常に完了するまでに非常に長い時間がかかる可能性があるため、現在指定されているタイムアウトの長さは設定されていません。 クラスターの詳細な状態とログを定期的に確認して、アップグレードが無期限にアップグレードを試行しているかどうかを判断します。

クラスターのログ、詳細メッセージ、詳細なステータス メッセージを確認することで、無期限に停止したアップグレードを特定できます。 この状態が発生した場合は、クラスターが進行せずに同じ状態を継続的に調整しているのを確認します。 クラスター ログまたは構成済みの Log Analytics ワークスペース (LAW) を確認し、処理が進まない原因となっている障害や特定の手順がないか確認します。

ベアメタル マシン アップグレードの一時停止/完全停止の特定

ワーカー ノードのプロビジョニングに関する問題を特定するためのガイドは、 ベア メタル マシン プロビジョニングのトラブルシューティングで提供されています。

ハードウェア障害ではアップグレードの再実行は必要ない

アップグレード中にハードウェア障害が発生しても、コンピューティング ノードと管理および制御ノードに設定されているしきい値が満たされている限り、ランタイム アップグレードは続行されます。 マシンが修理または交換されると、現在のプラットフォーム ランタイムの OS でプロビジョニングされ、これには対象となるバージョンのランタイムが含まれます。 障害の前にラックが更新された場合、ノードの再プロビジョニング時にはアップグレードされたランタイム バージョンが使われます。 ハードウェア障害が発生する前に、ラックの仕様がアップグレードされたランタイム バージョンに更新されなかった場合、マシンはハードウェアの修復時に以前のランタイム バージョンをプロビジョニングします。 ラックのアップグレードを開始すると、ラックと共にマシンがアップグレードされます。

ランタイム アップグレード後、クラスターに "Failed" プロビジョニング状態が表示されます

実行時のアップグレード中に、クラスターは Upgradingの状態になります。 ランタイムのアップグレードが失敗した場合、クラスターは Failed プロビジョニング状態になります。 インフラストラクチャ コンポーネント (ストレージ アプライアンスなど) は、アップグレード中にエラーを引き起こす可能性があります。 一部のシナリオでは、Microsoftサポートを使用してエラーを診断することが必要な場合があります。

ランタイム更新後にベア メタル マシンが機能低下を示す

状況によっては、ノードが Degraded 状態で返される場合があります。 この状態は、「 機能低下状態エラーのトラブルシューティング 」で見つかったいずれかの条件が満たされた場合に発生します。 低下状態は、基になる問題が解決されるまでノードで新しいワークロードがスケジュールされないように、ノードが自動的に切断されることを意味します。