Azure CLI を使用してクラスターを作成およびプロビジョニングする

[アーティクル]
11/01/2024

この記事では、Azure コマンドラインインターフェイス (AzCLI) を使用してクラスターを作成する方法について説明します。このドキュメントでは、クラスターの状態の確認、更新、または削除の方法についても説明します。

前提条件

Azure リージョンにネットワークファブリックコントローラーとクラスターマネージャーが存在することを確認する
ネットワークファブリックが正常にプロビジョニングされたことを確認する

API ガイドとメトリック

API ガイドには、リソースプロバイダーとリソースモデル、API に関する情報が記載されています。

ログデータから生成されたメトリックは、Azure Monitor メトリックで使用できます。

制限事項

名前付け - 名前付けルールについては、こちらを参照してください。

クラスターの作成

インフラストラクチャクラスターリソースは、クラスターマネージャー内のプラットフォームのオンプレミスデプロイを表します。他のプラットフォーム固有のリソースはすべて、そのライフサイクルの間、これに依存します。

このオンプレミスの展開の前に、ネットワークファブリックを作成する必要があります。各 Operator Nexus オンプレミスインスタンスとネットワークファブリックの間には 1 対 1 の関連付けがあります。

Azure CLI を使用してクラスターを作成します。

az networkcloud cluster create --name "$CLUSTER_NAME" --location "$LOCATION" \
  --extended-location name="$CL_NAME" type="CustomLocation" \
  --resource-group "$CLUSTER_RG" \
  --analytics-workspace-id "$LAW_ID" \
  --cluster-location "$CLUSTER_LOCATION" \
  --network-rack-id "$AGGR_RACK_RESOURCE_ID" \
  --rack-sku-id "$AGGR_RACK_SKU"\
  --rack-serial-number "$AGGR_RACK_SN" \
  --rack-location "$AGGR_RACK_LOCATION" \
  --bare-metal-machine-configuration-data "["$AGGR_RACK_BMM"]" \
  --storage-appliance-configuration-data '[{"adminCredentials":{"password":"$SA_PASS","username":"$SA_USER"},"rackSlot":1,"serialNumber":"$SA_SN","storageApplianceName":"$SA_NAME"}]' \
  --compute-rack-definitions '[{"networkRackId": "$COMPX_RACK_RESOURCE_ID", "rackSkuId": "$COMPX_RACK_SKU", "rackSerialNumber": "$COMPX_RACK_SN", "rackLocation": "$COMPX_RACK_LOCATION", "storageApplianceConfigurationData": [], "bareMetalMachineConfigurationData":[{"bmcCredentials": {"password":"$COMPX_SVRY_BMC_PASS", "username":"$COMPX_SVRY_BMC_USER"}, "bmcMacAddress":"$COMPX_SVRY_BMC_MAC", "bootMacAddress":"$COMPX_SVRY_BOOT_MAC", "machineDetails":"$COMPX_SVRY_SERVER_DETAILS", "machineName":"$COMPX_SVRY_SERVER_NAME"}]}]'\
  --managed-resource-group-configuration name="$MRG_NAME" location="$MRG_LOCATION" \
  --network fabric-id "$NF_ID" \
  --cluster-service-principal application-id="$SP_APP_ID" \
    password="$SP_PASS" principal-id="$SP_ID" tenant-id="$TENANT_ID" \
  --subscription "$SUBSCRIPTION_ID" \
  --secret-archive "{key-vault-id:$KVRESOURCE_ID, use-key-vault:true}" \
  --cluster-type "$CLUSTER_TYPE" --cluster-version "$CLUSTER_VERSION" \
  --tags $TAG_KEY1="$TAG_VALUE1" $TAG_KEY2="$TAG_VALUE2"

クラスター操作のパラメーター

パラメーター名	説明
CLUSTER_NAME	クラスターのリソース名
LOCATION	クラスターがデプロイされる Azure リージョン
CL_NAME	Azure portal のクラスターマネージャーのカスタムの場所
CLUSTER_RG	クラスターリソースグループ名
LAW_ID	クラスターの Log Analytics ワークスペース ID
CLUSTER_LOCATION	クラスターのローカル名
AGGR_RACK_RESOURCE_ID	アグリゲーターラックの RackID
AGGR_RACK_SKU	アグリゲーターラックのラック SKU *「Operator Nexus ネットワーククラウド SKU」を参照してください
AGGR_RACK_SN	アグリゲーターラックのラックのシリアル番号
AGGR_RACK_LOCATION	アグリゲーターラックのラックの物理的な場所
AGGR_RACK_BMM	単一ラック展開の場合にのみ使い、マルチラックの場合は空にします
SA_NAME	ストレージアプライアンスデバイス名
SA_PASS	ストレージアプライアンス管理者のパスワード
SA_USER	ストレージアプライアンス管理者ユーザー
SA_SN	ストレージアプライアンスのシリアル番号
COMPX_RACK_RESOURCE_ID	CompX ラックの RackID: compute-rack-definitions 内の各ラックに対して繰り返します
COMPX_RACK_SKU	CompX ラックのラック SKU。compute-rack-definitions 内の各ラックに対して繰り返します *「Operator Nexus ネットワーククラウド SKU」を参照してください
COMPX_RACK_SN	CompX ラックのラックのシリアル番号: compute-rack-definitions 内の各ラックに対して繰り返します
COMPX_RACK_LOCATION	CompX ラックのラックの物理的な場所: compute-rack-definitions 内の各ラックに対して繰り返します
COMPX_SVRY_BMC_PASS	CompX ラック ServerY ベースボード管理コントローラー (BMC) のパスワード (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
COMPX_SVRY_BMC_USER	CompX ラック ServerY BMC のユーザー (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
COMPX_SVRY_BMC_MAC	CompX ラック ServerY BMC の MAC アドレス (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
COMPX_SVRY_BOOT_MAC	CompX ラック ServerY ブートネットワークインターフェイスカード (NIC) の MAC アドレス (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
COMPX_SVRY_SERVER_DETAILS	CompX ラック ServerY の詳細 (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
COMPX_SVRY_SERVER_NAME	CompX ラック ServerY の名前 (compute-rack-definitions の各ラックとラック内の各サーバーに対して繰り返します)
MRG_NAME	クラスター管理対象リソースグループ名
MRG_LOCATION	クラスターの Azure リージョン
NF_ID	ネットワークファブリックへの参照
SP_APP_ID	サービスプリンシパルのアプリ ID
SP_PASS	サービスプリンシパルのパスワード
SP_ID	サービスプリンシパル ID
TENANT_ID	サブスクリプションテナント ID
SUBSCRIPTION_ID	サブスクリプション ID
KV_RESOURCE_ID	Key Vault ID
CLUSTER_TYPE	クラスターの種類 (Single または MultiRack)
CLUSTER_VERSION	クラスターのネットワーククラウド (NC) のバージョン
TAG_KEY1	クラスター作成に渡す省略可能な tag1
TAG_VALUE1	クラスター作成に渡す省略可能な tag1 値
TAG_KEY2	クラスター作成に渡す省略可能な tag2
TAG_VALUE2	クラスター作成に渡す省略可能な tag2 値

クラスター ID

2024-07-01 API バージョンから、顧客がクラスターにマネージド ID を割り当てることができます。システム割り当てとユーザー割り当ての両方のマネージド ID がサポートされています。

マネージド ID は、次のパラメーターを指定することで、作成操作または更新操作中にクラスターに割り当てることができます。

--mi-system-assigned - システム割り当てマネージド ID を有効にします。追加した ID は、現時点では API 呼び出しによってのみ削除できます。
--mi-user-assigned - 追加するユーザー割り当てマネージド ID のスペース区切りのリソース ID。追加した ID は、現時点では API 呼び出しによってのみ削除できます。

Azure Resource Manager テンプレートエディターを使ってクラスターを作成する

クラスターを作成するもう 1 つの方法は、ARM テンプレートエディターを使うことです。

この方法でクラスターを作成するには、テンプレートファイル (cluster.jsonc) とパラメーターファイル (cluster.parameters.jsonc) を指定する必要があります。これら 2 つのファイルを使う 8 ラック 2M16C SKU クラスターの例については、次を参照してください。

cluster.jsonc、cluster.parameters.jsonc

Note

正しい書式を取得するには、未加工のコードファイルをコピーします。 cluster.parameters.jsonc ファイル内の値は顧客固有であり、完全なリストではない可能性があります。特定の環境に合わせて値フィールドを更新してください。

Web ブラウザーで Azure portal に移動してサインインします。
Azure portal の検索バーで 'カスタムテンプレートのデプロイ' を検索し、使用できるサービスからそれを選びます。
[エディターで独自のテンプレートを作成する] をクリックします。
[ファイルの読み込み] をクリックします。 cluster.jsonc テンプレートファイルを見つけてアップロードします。
[保存] をクリックします。
[パラメーターの編集] をクリックします。
[ファイルの読み込み] をクリックします。 cluster.parameters.jsonc パラメーターファイルを見つけてアップロードします。
[保存] をクリックします。
適切なサブスクリプションを選択します。
リソースグループを検索して、既に存在するかどうかを確認します。ない場合は、新しいリソースグループを作成します。
すべてのインスタンス詳細が正しいことを確認します。
[Review + create](レビュー + 作成) をクリックします。

クラスターの検証テスト

Operator Nexus クラスターの作成に成功すると、サブスクリプション内に Azure リソースが作成されます。 cluster create が成功すると、クラスター ID、クラスターのプロビジョニング状態、デプロイ状態が返されます。

クラスターの状態を確認する:

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --cluster-name "$CLUSTER_RESOURCE_NAME"

リソースの provisioningState が表示されたら、クラスターの作成は完了です: "provisioningState": "Succeeded"

クラスターのログ記録

クラスターの作成ログは、次の場所で確認できます。

Azure portal の Resource または ResourceGroup のアクティビティログ。
コマンドラインで--debug フラグを渡した Azure CLI。

クラスターを展開する

クラスターを作成した後、クラスターのデプロイアクションをトリガーできます。クラスターのデプロイアクションによって、ブートストラップイメージが作成され、クラスターがデプロイされます。

クラスターのデプロイにより、クラスターマネージャーで一連のイベントが開始されます

クラスターとラックのプロパティの検証。
エフェメラルブートストラップクラスターの起動可能イメージの生成 (インフラストラクチャの検証)。
対象のブートストラップマシンの Intelligent Platform Management Interface (IPMI) インターフェイスの操作。
ハードウェア検証チェックの実行。
クラスターのデプロイプロセスの監視。

オンプレミスのクラスターを展開する:

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --no-wait --debug

ヒント

az networkcloud cluster deploy コマンドの状態を確認するには、--debug フラグを使用して実行します。これにより、operationStatuses リソースのクエリに使用する Azure-AsyncOperation または Location ヘッダーを取得できます。詳細な手順については、「クラスターデプロイ失敗」セクションを参照してください。必要に応じて、コマンドは --no-wait フラグを使用して非同期的に実行できます。

ハードウェア検証を使用したクラスターのデプロイ

クラスターのデプロイプロセス中に実行される手順の 1 つは、ハードウェアの検証です。ハードウェア検証手順では、さまざまなテストを実行し、クラスターのラック定義を通じて提供されたマシンに対してチェックを行います。これらのチェックの結果と、ユーザーがスキップしたマシンに基づいて、デプロイを続行するために必要なしきい値を満たすのに十分なノードが渡されたかどうか、または使用可能かどうかの判断が行われます。

重要

ハードウェア検証プロセスは、クラスターの作成時に指定した analyticsWorkspaceId に結果を書き込みます。さらに、クラスターオブジェクトに指定されたサービスプリンシパルは、Log Analytics ワークスペースデータ収集 API に対する認証に使用されます。この機能は、新しいデプロイ中にのみ表示されます (グリーンフィールド)。既存のクラスターでは、ログはさかのぼって使用できません。

Note

クラスターのデプロイ中に RAID コントローラーがリセットされて、サーバーの仮想ディスクからすべてのデータがワイプされます。通常、ベースボード管理コントローラー (BMC) の仮想ディスクアラートはすべて、物理ディスクや RAID コントローラーにそれ以外のアラートがない限り無視できます。

既定では、ハードウェア検証プロセスによって、構成されたクラスター analyticsWorkspaceId に結果が書き込まれます。ただし、Log Analytics ワークスペースのデータ収集とスキーマ評価の性質上、インジェストの遅延が発生し、数分以上かかる場合があります。このため、Log Analytics ワークスペースに結果を書き込めなかった場合でも、クラスターのデプロイが続行されます。この可能性のあるイベントに対処するために、冗長性のために結果もクラスターマネージャー内に記録されます。

指定されたクラスターオブジェクトの Log Analytics ワークスペースに、クラスター名がプレフィックスとして、サフィックスが *_CL である新しいカスタムテーブルが表示されます。 LAW リソースの Logs セクションでは、新しい *_CL カスタムログテーブルに対してクエリを実行できます。

特定のベアメタルマシンをスキップするクラスターデプロイ

--skip-validation-for-machines パラメーターは、ハードウェア検証の間にスキップする必要がある、クラスター内のベアメタルマシンの名前を表します。スキップされたノードは検証されず、ノードプールに追加されません。さらに、スキップされたノードは、しきい値の計算で使用された合計に対してカウントされません。

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --skip-validations-for-machines "$COMPX_SVRY_SERVER_NAME"

クラスターデプロイ失敗

非同期操作の状態を追跡するには、--debug フラグを有効にして実行します。 --debug を指定すると、要求の進行状況を監視できます。操作の状態 URL は、作成要求に対する HTTP 応答で Azure-AsyncOperation または Location ヘッダーを探してデバッグ出力を調べることで確認できます。ヘッダーは、HTTP API 呼び出しで使用される OPERATION_ID フィールドを提供できます。

OPERATION_ID="12312312-1231-1231-1231-123123123123*99399E995..."
az rest -m GET -u "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/providers/Microsoft.NetworkCloud/locations/${LOCATION}/operationStatuses/${OPERATION_ID}?api-version=2022-12-12-preview"

出力は JSON 構造体の例に似ています。エラーコードが HardwareValidationThresholdFailed の場合、ハードウェアの検証が失敗したベアメタルコンピューターの一覧がエラーメッセージに含まれます (COMP0_SVR0_SERVER_NAME、COMP1_SVR1_SERVER_NAME など)。これらの名前を使用して、ログを解析して詳細を確認できます。

{
  "endTime": "2023-03-24T14:56:59.0510455Z",
  "error": {
    "code": "HardwareValidationThresholdFailed",
    "message": "HardwareValidationThresholdFailed error hardware validation threshold for cluster layout plan is not met for cluster $CLUSTER_NAME in namespace nc-system with listed failed devices $COMP0_SVR0_SERVER_NAME, $COMP1_SVR1_SERVER_NAME"
  },
  "id": "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.NetworkCloud/locations/$LOCATION/operationStatuses/12312312-1231-1231-1231-123123123123*99399E995...",
  "name": "12312312-1231-1231-1231-123123123123*99399E995...",
  "resourceId": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$CLUSTER_RESOURCE_GROUP/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME",
  "startTime": "2023-03-24T14:56:26.6442125Z",
  "status": "Failed"
}

別の例については、「Azure CLI を使用した非同期操作の追跡」に関する記事を参照してください。特定のマシンが検証またはデプロイに失敗した場合に役立つ可能性のある情報については、「BMM プロビジョニングのトラブルシューティング」の記事を参照してください。

クラスターのデプロイ検証

ポータル上で、または Azure CLI を使用して、クラスターの状態を表示します。

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --name "$CLUSTER_NAME"

detailedStatus が Deploying に設定され、detailedStatusMessage にデプロイの進行状況が示される場合、クラスターのデプロイは進行中です。 detailedStatusMessage で示されるデプロイの進行状況の例としては、Hardware validation is in progress. (クラスターがハードウェア検証を使ってデプロイされている場合)、Cluster is bootstrapping.、KCP initialization in progress.、Management plane deployment in progress.、Cluster extension deployment in progress.、waiting for "<rack-ids>" to be ready などがあります。

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

クラスターの管理バージョンを表示します:

az k8s-extension list --cluster-name "$CLUSTER_NAME" --resource-group "$MRG_NAME" --cluster-type connectedClusters --query "[?name=='nc-platform-extension'].{name:name, extensionType:extensionType, releaseNamespace:scope.cluster.releaseNamespace,provisioningState:provisioningState,version:version}" -o table --subscription "$SUBSCRIPTION_ID"

クラスターのデプロイログ

クラスターの作成ログは、次の場所で確認できます。

Azure portal の Resource または ResourceGroup のアクティビティログ。
コマンドラインで--debug フラグを渡した Azure CLI。

API 経由でクラスター ID を更新する

クラスターのマネージド ID は、CLI 経由で割り当てることができます。 ID の割り当ての解除は、API 呼び出し経由で行うことができます。 <APIVersion> は API バージョン 2024-07-01 以降であることに注意してください。

すべてのマネージド ID を削除するには、次を実行します。

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body "{\"identity\":{\"type\":\"None\"}}"

ユーザー割り当てマネージド ID とシステム割り当てマネージド ID の両方が追加された場合は、type を SystemAssigned に更新することで、ユーザー割り当て ID を削除できます。
```
az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json
```
要求本文 (uai-body.json) の例:
```
{
  "identity": {
      "type": "SystemAssigned"
  }
}
```

ユーザー割り当てマネージド ID とシステム割り当てマネージド ID の両方が追加された場合は、type を UserAssigned に更新することで、システム割り当て ID を削除できます。

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

要求本文 (uai-body.json) の例:

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": {}
  	}
  }
}

複数のユーザー割り当てマネージド ID が追加された場合は、次を実行してそのうちの 1 つを削除できます。

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

要求本文 (uai-body.json) の例:

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": null
  	}
  }
}

クラスターの削除

クラスターを削除すると、Azure 内のリソースと、オンプレミス環境に存在するクラスターが削除されます。

Note

クラスター内に置かれたテナントリソースがある場合、それらのリソースが削除されるまで削除されません。

az networkcloud cluster delete --name "$CLUSTER_NAME" --resource-group "$CLUSTER_RG"

次の方法で共有

Azure CLI を使用してクラスターを作成およびプロビジョニングする

前提条件

API ガイドとメトリック

制限事項

クラスターの作成

Azure CLI を使用してクラスターを作成します。

クラスター操作のパラメーター

クラスター ID

Azure Resource Manager テンプレートエディターを使ってクラスターを作成する

クラスターの検証テスト

クラスターのログ記録

クラスターを展開する

ハードウェア検証を使用したクラスターのデプロイ

特定のベアメタルマシンをスキップするクラスターデプロイ

クラスターデプロイ失敗

クラスターのデプロイ検証

クラスターのデプロイログ

API 経由でクラスター ID を更新する

クラスターの削除

フィードバック

その他のリソース

次の方法で共有

Azure CLI を使用してクラスターを作成およびプロビジョニングする

前提条件

API ガイドとメトリック

制限事項

クラスターの作成

Azure CLI を使用してクラスターを作成します。

クラスター操作のパラメーター

クラスター ID

Azure Resource Manager テンプレート エディターを使ってクラスターを作成する

クラスターの検証テスト

クラスターのログ記録

クラスターを展開する

ハードウェア検証を使用したクラスターのデプロイ

特定のベア メタル マシンをスキップするクラスター デプロイ

クラスター デプロイ失敗

クラスターのデプロイ検証

クラスターのデプロイ ログ

API 経由でクラスター ID を更新する

クラスターの削除

フィードバック

その他のリソース

Azure Resource Manager テンプレートエディターを使ってクラスターを作成する

特定のベアメタルマシンをスキップするクラスターデプロイ

クラスターデプロイ失敗

クラスターのデプロイログ