Creare ed eseguire il provisioning di un cluster tramite l'interfaccia della riga di comando di Azure

Questo articolo descrive come creare un cluster usando l'interfaccia della riga di comando di Azure (AzCLI). Questo documento descrive anche come controllare lo stato, eseguire l'aggiornamento o eliminare un cluster.

Prerequisiti

• Assicurarsi che Network Fabric Controller e Cluster Manager esistano nell'area di Azure
• Assicurarsi che il provisioning di Network Fabric sia stato eseguito correttamente

Guida delle API e metriche

La guida delle API fornisce informazioni sui provider di risorse, sui modelli di risorse e sulle API.

Le metriche generate dai dati di registrazione sono disponibili nelle metriche di Monitoraggio di Azure.

Limiti

• Denominazione: le regole di denominazione sono disponibili qui.

Creare un cluster

La risorsa cluster dell'infrastruttura rappresenta una distribuzione locale della piattaforma all'interno di Cluster Manager. Tutte le altre risorse specifiche della piattaforma dipendono da questa per il loro ciclo di vita.

È necessario creare l'infrastruttura di rete prima di questa distribuzione locale. Ogni istanza locale dell'operatore Nexus ha un'associazione uno-a-uno con Network Fabric.

Creare il cluster usando l'interfaccia della riga di comando di Azure:

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"

Parametri per le operazioni del cluster

Identità del cluster

A partire dalla versione dell'API 2024-07-01, un cliente può assegnare un'identità gestita a un cluster. Sono supportate sia le identità gestite assegnate dal sistema che le identità gestite assegnate dall'utente.

L'identità gestita può essere assegnata al cluster durante le operazioni di creazione o aggiornamento fornendo i parametri seguenti:

• --mi-system-assigned - Abilitare l'identità gestita assegnata dal sistema. Dopo l'aggiunta, l'identità può essere rimossa solo tramite la chiamata API in questo momento.
• --mi-user-assigned - ID risorsa separati da spazio delle identità gestite assegnate dall'utente da aggiungere. Dopo l'aggiunta, l'identità può essere rimossa solo tramite la chiamata API in questo momento.

Creare un cluster usando l'editor modelli di Azure Resource Manager

Un modo alternativo per creare un cluster è costituito dalll'editor modelli di Resource Manager.

Per creare il cluster in questo modo, è necessario fornire un file modello (cluster.jsonc) e un file di parametri (cluster.parameters.jsonc). È possibile trovare esempi per un cluster SKU 2M16C a 8 rack usando questi due file:

cluster.jsonc, cluster.parameters.jsonc

1. Passare a portale di Azure in un Web browser e accedere.
2. Cercare "Deploy a custom template" (Distribuisci un modello personalizzato) nella barra di ricerca portale di Azure e quindi selezionarlo dai servizi disponibili.
3. Fare clic su Crea un modello personalizzato nell'editor.
4. Fare clic su Carica file. Individuare il file modello cluster.jsonc e caricarlo.
5. Fare clic su Salva.
6. Fare clic su Modifica parametri.
7. Fare clic su Carica file. Individuare il file di parametri cluster.parameters.jsonc e caricarlo.
8. Fare clic su Salva.
9. Selezionare la sottoscrizione corretta.
10. Cercare il gruppo di risorse per controllare se esiste già. Se non esiste, creare un nuovo gruppo di risorse.
11. Assicurarsi che tutti i dettagli dell'istanza siano corretti.
12. Fare clic su Rivedi e crea.

Convalida del cluster

La creazione di un cluster Operator Nexus con esito positivo comporta la creazione di una risorsa di Azure all'interno della sottoscrizione. L'ID del cluster, lo stato di provisioning del cluster e lo stato di distribuzione vengono restituiti se l'operazione di cluster create riesce.

Visualizzare lo stato del cluster:

az networkcloud cluster show --cluster-name "<clusterName>" /
--resource-group "<resourceGroupName>" /
--subscription <subscriptionID>

La creazione del cluster è stata completata quando provisioningState per la risorsa è: "provisioningState": "Succeeded"

Registrazione di cluster

I log di creazione del cluster possono essere visualizzati nelle posizioni seguenti:

1. Log attività Resource/ResourceGroup del portale di Azure.
2. Interfaccia della riga di comando di Azure con il flag --debug passato nella riga di comando.

Impostare le soglie di distribuzione

Esistono due tipi di soglie di distribuzione che possono essere impostate in un cluster prima della distribuzione del cluster. Si tratta di compute-deployment-threshold e update-strategy.

--compute-deployment-threshold: soglia di convalida che indica gli errori consentiti dei nodi di calcolo durante la convalida dell'hardware dell'ambiente.

Se compute-deployment-threshold non è impostato, le impostazioni predefinite sono le seguenti:

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

Se il cliente richiede un valore compute-deployment-threshold diverso dal valore predefinito dell'80%, è possibile eseguire il comando di aggiornamento del cluster seguente.

L'esempio seguente è relativo a un cliente che richiede il tipo "PercentSuccess" con una percentuale di successo del 97%.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--compute-deployment-threshold type="PercentSuccess" grouping="PerCluster" value=97 /
--subscription <subscriptionID>

Convalidare l'aggiornamento

az networkcloud cluster show --resource-group "<resourceGroup>" --name "<clusterName>" | grep -a3 computeDeploymentThreshold

  "clusterType": "MultiRack",
  "clusterVersion": "<CLUSTER_VERSION>",
  "computeDeploymentThreshold": {
    "grouping": "PerCluster",
    "type": "PercentSuccess",
    "value": 97

In questo esempio, se meno del 97% dei nodi di calcolo distribuiti supera la convalida hardware, la distribuzione del cluster avrà esito negativo. NOTA: tutti i piani di controllo kubernetes (KCP) e il piano di gestione nexus (NMP) devono superare la convalida hardware. Se il 97% o più nodi di calcolo distribuiti superano la convalida hardware, la distribuzione del cluster continuerà alla fase di provisioning bootstrap. Durante il provisioning bootstrap di calcolo, viene usato ( update-strategy di seguito) per i nodi di calcolo.

--update-strategy: strategia per l'aggiornamento del cluster che indica gli errori consentiti dei nodi di calcolo durante il provisioning bootstrap.

Se il cliente richiede una update-strategy soglia diversa dal valore predefinito dell'80%, è possibile eseguire il comando di aggiornamento del cluster seguente.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value="<thresholdValue>" wait-time-minutes=<waitTimeBetweenRacks> /
--subscription <subscriptionID>

Il tipo di strategia può essere "Rack" (rack per rack) O "PauseAfterRack" (attendere che la risposta del cliente continui).

Il tipo soglia può essere "PercentSuccess" O "CountSuccess".

Se updateStrategy non è impostato, le impostazioni predefinite sono le seguenti:

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

L'esempio seguente è destinato a un cliente che usa la strategia Rack by Rack con percentuale di successo del 60% e una pausa di 1 minuto.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value=60 wait-time-minutes=1 /
--subscription <subscriptionID>

Verificare l'aggiornamento:

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

In questo esempio, se meno del 60% dei nodi di calcolo di cui viene effettuato il provisioning in un rack non riescono a eseguire il provisioning (su rack per rack), la distribuzione del cluster avrà esito negativo. Se viene eseguito correttamente il provisioning del 60% o più nodi di calcolo, la distribuzione del cluster passa al rack successivo dei nodi di calcolo.

L'esempio seguente è destinato a un cliente che usa la strategia Rack per rack con un tipo di soglia CountSuccess di 10 nodi per rack e una pausa di 1 minuto.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" /
threshold-value=10 wait-time-minutes=1 /
--subscription <subscriptionID>

Verificare l'aggiornamento:

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

In questo esempio, se il provisioning di meno di 10 nodi di calcolo in un rack non riesce a eseguire il provisioning (su rack per rack), la distribuzione del cluster avrà esito negativo. Se viene eseguito correttamente il provisioning di 10 o più nodi di calcolo, la distribuzione del cluster passa al rack successivo dei nodi di calcolo.

Distribuire il cluster

L'azione deploy Cluster può essere attivata dopo la creazione del cluster. L'azione di distribuzione del cluster crea l'immagine bootstrap e distribuisce il cluster.

La distribuzione del cluster avvia una sequenza di eventi che si verificano in Cluster Manager.

1. Convalida delle proprietà cluster/rack.
2. Generazione di un'immagine di avvio per il cluster bootstrap temporaneo (convalida dell'infrastruttura).
3. Interazione con l'interfaccia IPMI (Intelligent Platform Management Interface) del computer bootstrap di destinazione.
4. Esecuzione di controlli di convalida hardware.
5. Monitoraggio del processo di distribuzione del cluster.

Distribuire il cluster in locale:

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

Distribuzione del cluster con convalida hardware

Durante un processo di distribuzione cluster, uno dei passaggi eseguiti è la convalida hardware. La procedura di convalida hardware esegue vari test e controlli sui computer forniti tramite la definizione rack del cluster. In base ai risultati di questi controlli e a eventuali computer ignorati dall'utente, viene stabilito se i nodi passati siano sufficienti e/o disponibili per soddisfare le soglie necessarie per continuare la distribuzione.

Per impostazione predefinita, il processo di convalida hardware scrive i risultati nell'analyticsWorkspaceId del cluster configurato. Tuttavia, a causa della natura della raccolta dei dati e della valutazione dello schema dell'area di lavoro Log Analytics, potrebbe verificarsi un ritardo di alcuni minuti nell'inserimento. Per questo motivo, la distribuzione del cluster procede anche se non è stato possibile scrivere i risultati nell'area di lavoro Log Analytics. Per facilitare la gestione di questo evento possibile, i risultati, per ridondanza, vengono registrati anche all'interno di Cluster Manager.

Nell'area di lavoro Log Analytics dell'oggetto cluster specificata verrà visualizzata una nuova tabella personalizzata con il nome del cluster come prefisso e il suffisso *_CL. Nella sezione Log della risorsa LAW è possibile eseguire una query sulla nuova tabella di log personalizzata *_CL.

Distribuzione del cluster con ignorando un computer bare metal specifico

Il --skip-validation-for-machines parametro rappresenta i nomi dei computer bare metal nel cluster che devono essere ignorati durante la convalida hardware. I nodi ignorati non vengono convalidati e non vengono aggiunti al pool di nodi. Inoltre, i nodi ignorati non vengono conteggiati rispetto al totale usato dai calcoli di soglia.

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

Distribuzione del cluster non riuscita

Per tenere traccia dello stato di un'operazione asincrona, eseguire l'operazione con un flag --debug abilitato. Quando si specifica --debug, è possibile monitorare lo stato della richiesta. È possibile trovare l'URL dello stato dell'operazione esaminando l'output di debug cercando l'intestazione Azure-AsyncOperation o Location nella risposta HTTP alla richiesta di creazione. Le intestazioni possono fornire il campo OPERATION_ID usato nella chiamata API HTTP.

OPERATION_ID="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*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"

L'output è simile all'esempio di struttura JSON seguente. Quando il codice di errore è HardwareValidationThresholdFailed, il messaggio di errore contiene un elenco di computer bare metal che non hanno superato la convalida hardware (ad esempio COMP0_SVR0_SERVER_NAME, COMP1_SVR1_SERVER_NAME). Questi nomi possono essere usati per analizzare i log per ulteriori dettagli.

{
  "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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995...",
  "name": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995...",
  "resourceId": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$CLUSTER_RESOURCE_GROUP/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME",
  "startTime": "2023-03-24T14:56:26.6442125Z",
  "status": "Failed"
}

Per un altro esempio, vedere l'articolo Rilevamento delle operazioni asincrone tramite l'interfaccia della riga di comando di Azure. Vedere l'articolo Risolvere i problemi di provisioning di BMM per altre informazioni che possono essere utili in caso di errori di convalida o distribuzione di computer specifici.

Convalida della distribuzione del cluster

Visualizzare lo stato del cluster nel portale o tramite l'interfaccia della riga di comando di Azure:

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

La distribuzione del cluster è in corso quando detailedStatus è impostato su Deploying e detailedStatusMessage mostra lo stato della distribuzione. Alcuni esempi di avanzamento della distribuzione illustrati in dettaglioStatusMessage sono Hardware validation is in progress. (se il cluster viene distribuito con convalida hardware), Cluster is bootstrapping., KCP initialization in progress.Management plane deployment in progress., Cluster extension deployment in progress., , e waiting for "<rack-ids>" to be readycosì via.

La distribuzione del cluster è in corso quando detailedStatus è impostato su Running e detailedStatusMessage mostra il messaggio Cluster is up and running.

Visualizzare la versione di gestione del cluster:

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"

Registrazione della distribuzione del cluster

I log di creazione del cluster possono essere visualizzati nelle posizioni seguenti:

1. Log attività Resource/ResourceGroup del portale di Azure.
2. Interfaccia della riga di comando di Azure con il flag --debug passato nella riga di comando.

Aggiornare le identità del cluster tramite LE API

Le identità gestite del cluster possono essere assegnate tramite l'interfaccia della riga di comando. È possibile annullare l'assegnazione delle identità tramite chiamate API. Si noti che <APIVersion> l'API è la versione 2024-07-01 o successiva.

• Per rimuovere tutte le identità gestite, eseguire:

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

• Se sono state aggiunte identità gestite assegnate dall'utente e assegnate dal sistema, è possibile rimuovere l'attributo Assegnato dall'utente aggiornando in type SystemAssigned:

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

  Esempio del corpo della richiesta (uai-body.json):

  {
    "identity": {
        "type": "SystemAssigned"
    }
  }
  

• Se sono state aggiunte identità gestite assegnate dall'utente e assegnate dal sistema, l'assegnazione del sistema può essere rimossa aggiornando in type UserAssigned:

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

  Esempio del corpo della richiesta (uai-body.json):

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

• Se sono state aggiunte più identità gestite assegnate dall'utente, è possibile rimuoverle eseguendo:

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

  Esempio del corpo della richiesta (uai-body.json):

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

Eliminare un cluster

L'eliminazione di un cluster elimina le risorse in Azure e il cluster che si trova nell'ambiente locale.

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