Créer et approvisionner un cluster à l’aide d’Azure CLI

Cet article explique comment créer un cluster à l’aide de l’interface de ligne de commande Azure (AzCLI). Ce document vous montre également comment vérifier l’état d’un cluster, le mettre à jour ou le supprimer.

Prérequis

• Vérifier que le contrôleur de structure réseau et le gestionnaire de cluster existent dans votre région Azure
• Vérifier que Network Fabric est correctement approvisionné

Guide et métriques d’API

Le guide d’API fournit des informations sur les fournisseurs de ressources et les modèles de ressources, ainsi que sur les API.

Les métriques générées à partir des données de journalisation sont disponibles dans les métriques Azure Monitor.

Limites

• Nommage : les règles de nommage sont disponibles ici.

Créer un cluster

La ressource de cluster d’infrastructure représente un déploiement local de la plateforme dans le Gestionnaire de cluster. Toutes les autres ressources spécifiques à la plateforme en dépendent pour leur cycle de vie.

Vous devez créer l’instance Network Fabric avant ce déploiement local. Chaque instance Operator Nexus locale a une association un-à-un avec une structure réseau.

Créer le cluster à l’aide d’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"

Paramètres pour les opérations de cluster

Nom du paramètre	Description
CLUSTER_NAME	Nom de ressource de la ressource
LOCATION	Région Azure où le cluster est déployé
CL_NAME	Emplacement personnalisé du Gestionnaire de cluster à partir du portail Azure
CLUSTER_RG	Nom du groupe de ressources de cluster
LAW_ID	ID d’espace de travail Log Analytics pour le cluster
CLUSTER_LOCATION	Nom local du cluster
AGGR_RACK_RESOURCE_ID	ID de rack pour le rack Aggregator
AGGR_RACK_SKU	Référence SKU de rack pour le rack Aggregator *Consultez Références SKU du réseau cloud Operator Nexus
AGGR_RACK_SN	Numéro de série de rack pour le rack Aggregator
AGGR_RACK_LOCATION	Emplacement physique du rack pour le rack Aggregator
AGGR_RACK_BMM	Utilisé uniquement pour un déploiement à rack unique ; vide pour un déploiement multirack
SA_NAME	Nom d’appareil de l’appliance de stockage
SA_PASS	Mot de passe administrateur de l’appliance de stockage
SA_USER	Utilisateur administrateur de l’appliance de stockage
SA_SN	Numéro de série de l’appliance de stockage
COMPX_RACK_RESOURCE_ID	ID de rack pour le rack CompX ; répéter cette opération pour chaque rack dans compute-rack-definitions
COMPX_RACK_SKU	Référence SKU de rack pour le rack CompX ; répétez cette opération pour chaque rack dans compute-rack-definitions *Consultez Références SKU du réseau cloud Operator Nexus
COMPX_RACK_SN	Numéro de série de rack pour le rack CompX ; répéter cette opération pour chaque rack dans compute-rack-definitions
COMPX_RACK_LOCATION	Emplacement physique du rack pour le rack CompX ; répéter cette opération pour chaque rack dans compute-rack-definitions
COMPX_SVRY_BMC_PASS	Mot de passe du contrôleur de gestion de la carte de base (BMC) de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
COMPX_SVRY_BMC_USER	Utilisateur BMC de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
COMPX_SVRY_BMC_MAC	Adresse MAC BMC de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
COMPX_SVRY_BOOT_MAC	Adresse MAC de carte réseau de démarrage de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
COMPX_SVRY_SERVER_DETAILS	Détails de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
COMPX_SVRY_SERVER_NAME	Nom de serveur Y monté en rack CompX. Répétez cette opération pour chaque rack dans les définitions de rack de calcul et pour chaque serveur se trouvant dans le rack
MRG_NAME	Nom du groupe de ressources managées de cluster
MRG_LOCATION	Région Azure du cluster
NF_ID	Référence à l’instance Network Fabric
SP_APP_ID	ID d’application du principal de service
SP_PASS	Mot de passe du principal de service
SP_ID	ID de principal de service
TENANT_ID	ID de locataire d’abonnement
SUBSCRIPTION_ID	ID d’abonnement
KV_RESOURCE_ID	ID du coffre de clés
CLUSTER_TYPE	Type de cluster : monorack ou multirack
CLUSTER_VERSION	Version du cloud réseau (NC) de cluster
TAG_KEY1	Balise facultative 1 à passer à la création de cluster
TAG_VALUE1	Valeur de la balise facultative 1 à passer à la création de cluster
TAG_KEY2	Balise facultative 2 à passer à la création de cluster
TAG_VALUE2	Valeur de la balise facultative 2 à passer à la création de cluster

Identité de cluster

À compter de la version d’API 2024-07-01, un client peut attribuer une identité managée à un cluster. Les identités managées affectées par le système et affectées par l’utilisateur sont prises en charge.

L’identité managée peut être affectée au cluster au cours des opérations de création ou de mise à jour en fournissant les paramètres suivants :

• --mi-system-assigned : activez l’identité managée affectée par le système. Une fois ajoutée, l’identité peut uniquement être supprimée via l’appel d’API pour le moment.
• --mi-user-assigned : les ID de ressource séparés par des espaces des identités managées par l’utilisateur à ajouter. Une fois ajoutée, l’identité peut uniquement être supprimée via l’appel d’API pour le moment.

Créer le cluster à l’aide de l’éditeur de modèles Azure Resource Manager

Une autre façon de créer un cluster consiste à utiliser l’éditeur de modèles ARM.

Pour créer le cluster de cette façon, vous devez fournir un fichier de modèle (cluster.jsonc) et un fichier de paramètres (cluster.parameters.jsonc). Vous trouverez des exemples pour un cluster de référence SKU 2M16C à 8 racks utilisant ces deux fichiers :

cluster.jsonc , cluster.parameters.jsonc

Remarque

Pour obtenir la mise en forme appropriée, copiez le fichier de code brut. Les valeurs du fichier cluster.parameters.jsonc sont spécifiques au client et peuvent ne pas constituer une liste exhaustive. Mettez à jour les champs de valeurs en fonction de votre environnement.

1. Dans un navigateur web, accédez au portail Azure et connectez-vous.
2. Dans la barre de recherche du portail Azure, recherchez « Déployer un modèle personnalisé », puis sélectionnez-le dans les services disponibles.
3. Cliquez sur Créer votre propre modèle dans l’éditeur.
4. Cliquez sur Charger le fichier. Recherchez votre fichier de modèle cluster.jsonc et chargez-le.
5. Cliquez sur Enregistrer.
6. Cliquez sur Modifier les paramètres.
7. Cliquez sur Charger le fichier. Recherchez votre fichier de paramètres cluster.parameters.jsonc et chargez-le.
8. Cliquez sur Enregistrer.
9. Sélectionnez l’abonnement approprié.
10. Recherchez le groupe de ressources pour voir s’il existe déjà. Si ce n’est pas le cas, créez un groupe de ressources.
11. Vérifiez que tous les détails de l’instance sont corrects.
12. Cliquez sur Vérifier + créer.

Validation des clusters

La création réussie d’un cluster Operator Nexus entraîne la création d’une ressource Azure dans votre abonnement. L’ID de cluster, l’état d’approvisionnement du cluster et l’état de déploiement sont retournés suite à une opération cluster create réussie.

Consultez l’état du cluster :

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

La création du cluster est terminée lorsque la valeur provisioningState de la ressource affiche : "provisioningState": "Succeeded"

Journalisation des clusters

Vous pouvez consulter les journaux de création de cluster aux emplacements suivants :

1. Journaux d’activité Resource/ResourceGroup du portail Azure.
2. Azure CLI avec l’indicateur --debug passé sur la ligne de commande.

Déployer un cluster

L’action de déploiement du cluster peut être déclenchée après la création du cluster. L’action de déploiement de cluster crée l’image de démarrage et déploie le cluster.

L’action de déploiement de cluster déclenche une séquence d’événements dans le Gestionnaire de cluster.

1. Validation des propriétés du cluster/rack.
2. Génération d’une image de démarrage pour le cluster de démarrage éphémère (validation de l’infrastructure).
3. Interaction avec l’interface IPMI (Intelligent Platform Management Interface) de la machine de démarrage ciblée.
4. Exécution des vérifications de validation matérielle.
5. Monitoring du processus de déploiement de cluster.

Déployez le cluster local :

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

Conseil

Pour vérifier l’état de la commande az networkcloud cluster deploy, vous pouvez l’exécuter à l’aide de l’indicateur --debug. Cela vous permet d’obtenir l’en-tête Azure-AsyncOperation ou Location utilisé pour interroger la ressource operationStatuses. Pour plus d’informations, consultez la section Échec du déploiement du cluster. Si vous le souhaitez, la commande peut s’exécuter de manière asynchrone à l’aide de l’indicateur --no-wait.

Déploiement de cluster avec validation matérielle

Pendant un processus de déploiement de cluster, l’une des étapes exécutées est la validation matérielle. La procédure de validation matérielle exécute différents tests et vérifications sur les machines fournies via la définition de rack du cluster. En fonction des résultats de ces vérifications et de toutes les machines ignorées par l’utilisateur, une détermination est effectuée pour déterminer si des nœuds suffisants sont passés et/ou sont disponibles pour atteindre les seuils nécessaires au déploiement pour continuer.

Important

Le processus de validation matérielle écrit les résultats dans l’élément spécifié analyticsWorkspaceId lors de la création du cluster. En outre, le principal de service fourni dans l’objet Cluster est utilisé pour l’authentification auprès de l’API de collecte de données de l’espace de travail Log Analytics. Cette fonctionnalité est visible uniquement pendant un nouveau déploiement (champ vert). Le cluster existant ne dispose pas des journaux d’activité rétroactifs.

Remarque

Le contrôleur RAID est réinitialisé pendant le déploiement de cluster et toutes les données des disques virtuels du serveur sont effacées. Les alertes de disque virtuel du contrôleur de gestion de la carte de base (BMC) peuvent généralement être ignorées, sauf en cas d’alertes supplémentaires de disque physique et/ou de contrôleurs RAID.

Par défaut, le processus de validation matérielle écrit les résultats dans le cluster analyticsWorkspaceId configuré. Toutefois, en raison de la nature de la collecte de données de l’espace de travail Log Analytics et de l’évaluation du schéma, il peut y avoir un délai d’ingestion qui peut prendre plusieurs minutes ou plus. Pour cette raison, le déploiement du cluster se poursuit même s’il n’y a pas eu de défaillance pour écrire les résultats dans l’espace de travail Log Analytics. Pour résoudre cet événement possible, les résultats, pour la redondance, sont également enregistrés dans le Gestionnaire de cluster.

Dans l’espace de travail Log Analytics de l’objet cluster fourni, une nouvelle table personnalisée portant le nom du cluster comme préfixe et le suffixe *_CL doit apparaître. Dans la section Journaux de la ressource LAW, vous pouvez exécuter une requête sur la nouvelle table de journal personnalisé *_CL.

Déploiement de cluster en ignorant une machine nue spécifique

Le paramètre --skip-validation-for-machines représente les noms des machines nues du cluster qui doivent être ignorées pendant la validation matérielle. Les nœuds ignorés ne sont pas validés et ne sont pas ajoutés au pool de nœuds. En outre, les nœuds ignorés ne sont pas comptabilisés par rapport au total utilisé par les calculs de seuil.

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

Échec du déploiement de cluster

Pour suivre l’état d’une opération asynchrone, exécutez avec un indicateur --debug activé. Quand vous spécifiez --debug, vous pouvez superviser la progression de la requête. L’URL d’état de l’opération est disponible en examinant la sortie de débogage à la recherche de l’en-tête Azure-AsyncOperation ou Location de la réponse HTTP à la demande de création. Les en-têtes peuvent fournir le champ OPERATION_ID utilisé dans l’appel d’API HTTP.

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"

La sortie est similaire à l’exemple de struct JSON. Lorsque le code d’erreur est HardwareValidationThresholdFailed, le message d’erreur contient la liste des machines nues qui ont échoué à la validation matérielle (par exemple, COMP0_SVR0_SERVER_NAME, COMP1_SVR1_SERVER_NAME). Vous pouvez utiliser ces noms pour analyser les journaux pour plus d’informations.

{
  "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"
}

Consultez l’article Suivi des opérations asynchrones à l’aide d’Azure CLI pour obtenir un autre exemple. Lorsque la validation ou le déploiement de certaines machines échoue, vous pouvez obtenir des informations utiles en consultant l’article Résoudre les problèmes d’approvisionnement BMM.

Validation du déploiement d’un cluster

Affichez l'état du cluster sur le portail ou via Azure CLI :

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

Le déploiement du cluster est en cours lorsque detailedStatus est défini sur Deploying et detailedStatusMessage affiche la progression du déploiement. Voici quelques exemples de progression de déploiement affichés dans detailedStatusMessage : Hardware validation is in progress. (si le cluster est déployé avec validation matérielle), Cluster is bootstrapping., KCP initialization in progress., Management plane deployment in progress., Cluster extension deployment in progress., waiting for "<rack-ids>" to be ready, etc.

Le déploiement du cluster est terminé lorsque detailedStatus est défini sur Running et detailedStatusMessage affiche le message Cluster is up and running.

Affichez la version de gestion du 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"

Journalisation du déploiement d’un cluster

Vous pouvez consulter les journaux de création de cluster aux emplacements suivants :

1. Journaux d’activité Resource/ResourceGroup du portail Azure.
2. Azure CLI avec l’indicateur --debug passé sur la ligne de commande.

Mettre à jour les identités de cluster via des API

Vous pouvez affecter les identités managées du cluster via l’interface CLI. L’annulation d’affectation des identités peut être effectuée via des appels d’API. Notez que <APIVersion> est la version d’API 2024-07-01 ou une version plus récente.

• Pour supprimer toutes les identités managées, exécutez :

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

• Si des identités managées affectées par l’utilisateur et des identités managées affectées par le système ont été ajoutées, l’élément affecté par l’utilisateur peut être supprimé en remplaçant la valeur type par 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
  

  L’exemple de corps de la demande (uai-body.json) :

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

• Si des identités managées affectées par l’utilisateur et des identités managées affectées par le système ont été ajoutées, l’élément affecté par le système peut être supprimé en remplaçant la valeur type par 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
  

  L’exemple de corps de la demande (uai-body.json) :

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

• Si plusieurs identités managées affectées par l’utilisateur ont été ajoutées, l’une d’entre elles peut être supprimée en exécutant :

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

  L’exemple de corps de la demande (uai-body.json) :

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

Suppression d'un cluster

La suppression d’un cluster supprime les ressources dans Azure ainsi que le cluster qui réside dans l’environnement local.

Remarque

S’il existe des ressources de locataire dans le cluster, ce dernier ne sera pas supprimé tant que ces ressources ne seront pas supprimées.

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