Créer et attacher un cluster Azure Kubernetes Service avec v1

S’APPLIQUE À : SDK Python azureml v1

S’APPLIQUE À : Extension ml Azure CLI v1

Azure Machine Learning peut déployer des modèles Machine Learning entraînés sur Azure Kubernetes Service. Toutefois, vous devez d’abord créer un cluster Azure Kubernetes Service (AKS) à partir de votre espace de travail Azure Machine Learning ou attacher un cluster AKS existant. Cet article fournit des informations sur la création et l’attachement d’un cluster.

Prérequis

• Un espace de travail Azure Machine Learning. Pour plus d’informations, voir la page Créer un espace de travail Azure Machine Learning.

• L’extension Azure CLI (v1) pour Machine Learning service, le SDK Azure Machine Learning pour Python ou l’extension Azure Machine Learning pour Visual Studio Code.

  Important

  Certaines des commandes Azure CLI de cet article utilisent l’extension azure-cli-ml, ou v1, pour Azure Machine Learning. La prise en charge de l’extension v1 se termine le 30 septembre 2025. Vous pourrez installer et utiliser l’extension v1 jusqu’à cette date.

  Nous vous recommandons de passer à l’extension ml, ou v2, avant le 30 septembre 2025. Pour plus d’informations sur l’extension v2, consultez Extension Azure ML CLI et le SDK Python v2.

• Si vous envisagez d’utiliser un réseau virtuel Azure pour sécuriser la communication entre votre espace de travail Azure Machine Learning et le cluster AKS, votre espace de travail et ses ressources associées (stockage, coffre de clés, Azure Container Registry) doivent avoir des points de terminaison privés ou des points de terminaison de service dans le même réseau virtuel que le réseau virtuel du cluster AKS. Suivez le tutoriel Créer un espace de travail sécurisé pour ajouter ces points de terminaison privés ou points de terminaison de service à votre réseau virtuel.

Limites

• Un cluster AKS ne peut être créé ou attaché qu’en tant que cible de calcul unique dans l’espace de travail Azure Machine Learning. L’attachement multiple pour un même cluster AKS n’est pas pris en charge.

• Si vous devez déployer un équilibreur de charge standard (SLB) (Standard Load Balancer) au lieu d’un équilibreur de charge basique (BLB) (Basic Load Balancer) dans votre cluster, créez un cluster sur le portail AKS/l’interface CLI/le kit SDK, puis attachez-le à l’espace de travail Azure Machine Learning.

• Si vous avez une stratégie Azure Policy qui limite la création d’adresses IP publiques, la création du cluster AKS échouera. AKS a besoin d’une adresse IP publique pour le trafic de sortie. L’article relatif au trafic de sortie fournit également des conseils pour verrouiller le trafic sortant du cluster via l’IP publique, sauf pour quelques noms de domaine complets. Il existe deux façons d’activer une adresse IP publique :

  • Le cluster peut utiliser l’adresse IP publique créée par défaut avec l’équilibreur de charge BLB ou SLB, ou
  • Le cluster peut être créé sans adresse IP publique ; une adresse IP publique est alors configurée avec un pare-feu avec une route définie par l’utilisateur. Pour plus d’informations, consultez l’article Personnaliser la sortie du cluster avec une route définie par l’utilisateur.

  Le plan de contrôle Azure Machine Learning ne communique pas avec cette adresse IP publique. Il communique avec le plan de contrôle AKS pour les déploiements.

• Pour attacher un cluster AKS, le principal de service/l’utilisateur qui effectue l’opération doit se voir attribuer le rôle de contrôle d’accès en fonction du rôle (Azure RBAC) Propriétaire ou Contributeur sur le groupe de ressources Azure qui contient le cluster. Le principal du service/l’utilisateur doit également être affecté au rôle Administrateur de cluster Azure Kubernetes Service sur le cluster.

• Si vous attachez un cluster AKS pour lequel une plage d’adresses IP autorisées a accès au serveur d’API, activez les plages d’adresses IP du plan de contrôle Azure Machine Learning pour le cluster AKS. Le plan de contrôle Azure Machine Learning est déployé sur les régions jumelées et déploie des pods d’inférence sur le cluster AKS. Le déploiement des pods d’inférence n’est pas possible sans accès au serveur d’API. Utilisez les plages d’adresses IP des deux régions jumelées lors de l’activation des plages d’adresses IP dans un cluster AKS.

  Les plages d’adresses IP autorisées ne fonctionnent qu’avec Standard Load Balancer.

• Si vous voulez utiliser un cluster AKS privé (avec Azure Private Link), vous devez d’abord créer le cluster, puis l’attacher à l’espace de travail. Pour plus d’informations, consultez Créer un cluster Azure Kubernetes Service privé.

• L’utilisation d’un nom de domaine complet (FQDN) public avec un cluster AKS privé n’est pas prise en charge avec Azure Machine Learning.

• Le nom de calcul du cluster AKS DOIT être unique au sein de l’espace de travail Azure Machine Learning. Il peut inclure des lettres, des chiffres et des tirets. Il doit commencer par une lettre, se terminer par une lettre ou un chiffre, et contenir entre 3 et 24 caractères.

• Si vous souhaitez déployer des modèles sur des nœuds GPU ou FPGA (ou sur une référence SKU spécifique), vous devez créer un cluster de la référence SKU en question. Il n’est pas possible de créer un pool de nœuds secondaire dans un cluster existant et de déployer des modèles dans le pool de nœuds secondaire.

• Lors de la création ou de l’attachement d’un cluster, vous pouvez indiquer s’il sera utilisé dans un contexte de développement/test ou de production. Si vous souhaitez créer un cluster AKS à des fins de développement, de validation et de test plutôt que de production, définissez l’objet du cluster sur développement/test. Si vous n’indiquez pas l’objet du cluster, un cluster de production est créé.

  Important

  Un cluster de développement/test n’est pas approprié pour le trafic de production et peut augmenter les temps d’inférence. Par ailleurs, les clusters de développement/test ne garantissent pas une tolérance de panne.

• Lors de la création ou de l’attachement d’un cluster, si celui-ci est destiné à la production, il doit contenir au moins 3 nœuds. Pour un cluster dev-test, il doit contenir au moins 1 nœud.

• Le kit de développement logiciel (SDK) Azure Machine Learning ne prend pas en charge la mise à l’échelle d'un cluster AKS. Pour mettre à l’échelle les nœuds du cluster, utilisez l’interface utilisateur de votre cluster AKS dans Azure Machine Learning Studio. Vous pouvez modifier le nombre de nœuds, mais pas la taille de machine virtuelle du cluster. Pour plus d’informations sur la mise à l’échelle des nœuds d’un cluster AKS, consultez les articles suivants :

  • Mettre à l’échelle manuellement le nombre de nœuds dans un cluster AKS
  • Configurer l’utilitaire de mise à l’échelle automatique de cluster dans AKS

• Ne mettez pas directement à jour le cluster en utilisant une configuration YAML. Alors qu’Azure Kubernetes Services prend en charge les mises à jour via la configuration YAML, les déploiements Azure Machine Learning remplacent vos modifications. Les deux seuls champs YAML qui ne seront pas remplacés sont Limites des demande et UC et mémoire.

• La création d’un cluster AKS à l’aide de l’interface utilisateur, du kit de développement logiciel ou de l’extension CLI Azure Machine Learning Studio n’est pas idempotente. Toute tentative de création de la ressource entraîne une erreur indiquant qu’un cluster portant le même nom existe déjà.

  • L’utilisation d’un modèle Azure Resource Manager et de la ressource Microsoft.MachineLearningServices/workspaces/computes pour créer un cluster AKS n’est pas idempotente non plus. Si vous tentez d’utiliser à nouveau le modèle pour mettre à jour une ressource déjà existante, vous recevrez le même message d’erreur.

Version d’Azure Kubernetes Service

Azure Kubernetes Service vous permet de créer un cluster à l’aide de différentes versions de Kubernetes. Pour plus d’informations sur les versions disponibles, consultez Versions de Kubernetes prises en charge dans Azure Kubernetes Service.

Lorsque vous créez un cluster Azure Kubernetes Service à l’aide de l’une des méthodes suivantes, vous n’avez pas le choix de la version du cluster créé :

• Studio Azure Machine Learning ou section Azure Machine Learning du portail Azure.
• Extension Machine Learning pour l’interface de ligne de commande Azure.
• Kit de développement logiciel (SDK) Azure Machine Learning.

Ces méthodes de création d’un cluster AKS utilisent la version par défaut du cluster. La version par défaut change au fil du temps et de la publication de nouvelles versions de Kubernetes.

Lors de l’attachement d’un cluster AKS existant, nous prenons en charge toutes les versions d’AKS actuellement prises en charge.

Versions par défaut et disponibles

Pour trouver les versions AKS par défaut et disponibles, utilisez la commande Azure CLIaz aks get-versions. Par exemple, la commande suivante renvoie les versions disponibles dans la région USA Ouest :

az aks get-versions -l westus -o table

Le résultat de la commande se présente ainsi :

KubernetesVersion    Upgrades
-------------------  ----------------------------------------
1.18.6(preview)      None available
1.18.4(preview)      1.18.6(preview)
1.17.9               1.18.4(preview), 1.18.6(preview)
1.17.7               1.17.9, 1.18.4(preview), 1.18.6(preview)
1.16.13              1.17.7, 1.17.9
1.16.10              1.16.13, 1.17.7, 1.17.9
1.15.12              1.16.10, 1.16.13
1.15.11              1.15.12, 1.16.10, 1.16.13

Pour trouver la version par défaut utilisée lors de la création d’un cluster via Azure Machine Learning, vous pouvez utiliser le paramètre --query pour sélectionner la version par défaut :

az aks get-versions -l westus --query "orchestrators[?default == `true`].orchestratorVersion" -o table

Le résultat de la commande se présente ainsi :

Result
--------
1.16.13

Si vous souhaitez vérifier par programme les versions disponibles, utilisez l’API REST Container Service Client - List Orchestrators. Pour trouver les versions disponibles, repérez les entrées où orchestratorType est Kubernetes. Les entrées orchestrationVersion associées contiennent les versions disponibles qui peuvent être attachées à votre espace de travail.

Pour trouver la version par défaut utilisée lors de la création d’un cluster via Azure Machine Learning, trouvez l’entrée dans laquelle orchestratorType est Kubernetes et default est true. La valeur orchestratorVersion associée est la version par défaut. L’extrait de code JSON suivant est un exemple d’entrée :

...
 {
        "orchestratorType": "Kubernetes",
        "orchestratorVersion": "1.16.13",
        "default": true,
        "upgrades": [
          {
            "orchestratorType": "",
            "orchestratorVersion": "1.17.7",
            "isPreview": false
          }
        ]
      },
...

Créer un cluster AKS

Durée estimée : environ 10 minutes.

La création ou l’attachement d’un cluster AKS est un processus à effectuer une seule fois pour votre espace de travail. Vous pouvez le réutiliser pour vos autres déploiements. Si vous supprimez le cluster ou le groupe de ressources dans lequel il se trouve, vous devrez recréer un cluster lors du prochain déploiement. Vous pouvez avoir plusieurs clusters AKS attachés à votre espace de travail.

L’exemple suivant montre comment créer un cluster AKS à l’aide du Kit de développement logiciel (SDK) et de l’interface CLI :

from azureml.core.compute import AksCompute, ComputeTarget

# Use the default configuration (you can also provide parameters to customize this).
# For example, to create a dev/test cluster, use:
# prov_config = AksCompute.provisioning_configuration(cluster_purpose = AksCompute.ClusterPurpose.DEV_TEST)
prov_config = AksCompute.provisioning_configuration()

# Example configuration to use an existing virtual network
# prov_config.vnet_name = "mynetwork"
# prov_config.vnet_resourcegroup_name = "mygroup"
# prov_config.subnet_name = "default"
# prov_config.service_cidr = "10.0.0.0/16"
# prov_config.dns_service_ip = "10.0.0.10"
# prov_config.docker_bridge_cidr = "172.17.0.1/16"

aks_name = 'myaks'
# Create the cluster
aks_target = ComputeTarget.create(workspace = ws,
                                    name = aks_name,
                                    provisioning_configuration = prov_config)

# Wait for the create process to complete
aks_target.wait_for_completion(show_output = True)

az ml computetarget create aks -n myaks

Attacher un cluster AKS existant

Durée estimée : 5 minutes environ.

Si vous disposez déjà d’un cluster AKS dans votre abonnement Azure, vous pouvez l’utiliser avec votre espace de travail.

Pour plus d’informations sur la création d’un cluster AKS à l’aide de l’interface de ligne de commande Azure ou du portail, consultez les articles suivants :

• Créer un cluster AKS (CLI)
• Créer un cluster AKS (portail)
• Créer un cluster AKS (modèle ARM sur les modèles de démarrage rapide Azure)

L’exemple suivant montre comment attacher un cluster AKS existant à votre espace de travail :

from azureml.core.compute import AksCompute, ComputeTarget
# Set the resource group that contains the AKS cluster and the cluster name
resource_group = 'myresourcegroup'
cluster_name = 'myexistingcluster'

# Attach the cluster to your workgroup. If the cluster has less than 12 virtual CPUs, use the following instead:
# attach_config = AksCompute.attach_configuration(resource_group = resource_group,
#                                         cluster_name = cluster_name,
#                                         cluster_purpose = AksCompute.ClusterPurpose.DEV_TEST)
attach_config = AksCompute.attach_configuration(resource_group = resource_group,
                                         cluster_name = cluster_name)
aks_target = ComputeTarget.attach(ws, 'myaks', attach_config)

# Wait for the attach process to complete
aks_target.wait_for_completion(show_output = True)

az aks show -n myexistingcluster -g myresourcegroup --query id

/subscriptions/{GUID}/resourcegroups/{myresourcegroup}/providers/Microsoft.ContainerService/managedClusters/{myexistingcluster}

az ml computetarget attach aks -n myaks -i aksresourceid -g myresourcegroup -w myworkspace

Création ou attachement d’un cluster AKS avec terminaison TLS

Lorsque vous créez ou attachez un cluster AKS, vous pouvez activer la terminaison TLS avec les objets de configuration AksCompute.provisioning_configuration() et AksCompute.attach_configuration() . Les deux méthodes retournent un objet de configuration possédant une méthode enable_ssl, que vous pouvez utiliser pour activer le protocole TLS.

L’exemple suivant montre comment activer la terminaison TLS avec la génération et la configuration automatiques de certificats TLS en utilisant un certificat Microsoft.

S’APPLIQUE À : SDK Python azureml v1

   from azureml.core.compute import AksCompute, ComputeTarget
   
   # Enable TLS termination when you create an AKS cluster by using provisioning_config object enable_ssl method

   # Leaf domain label generates a name using the formula
   # "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
   # where "######" is a random series of characters
   provisioning_config.enable_ssl(leaf_domain_label = "contoso")
   
   # Enable TLS termination when you attach an AKS cluster by using attach_config object enable_ssl method

   # Leaf domain label generates a name using the formula
   # "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
   # where "######" is a random series of characters
   attach_config.enable_ssl(leaf_domain_label = "contoso")

L’exemple suivant montre comment activer la terminaison TLS avec un certificat personnalisé et un nom de domaine personnalisé. Avec un domaine et un certificat personnalisés, vous devez mettre à jour votre enregistrement DNS de sorte qu’il pointe vers l’adresse IP du point de terminaison de scoring (cf. Mise à jour d’un enregistrement DNS).

S’APPLIQUE À : SDK Python azureml v1

   from azureml.core.compute import AksCompute, ComputeTarget

   # Enable TLS termination with custom certificate and custom domain when creating an AKS cluster
   
   provisioning_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                        ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")
    
   # Enable TLS termination with custom certificate and custom domain when attaching an AKS cluster

   attach_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                        ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")

Création ou attachement d’un cluster AKS pour utiliser un Load Balancer interne avec une adresse IP privée

Lorsque vous créez ou attachez un cluster AKS, vous pouvez le configurer pour qu’il utilise un Load Balancer interne. Avec un Load Balancer interne, les points de terminaison de scoring des déploiements effectués sur AKS utiliseront une adresse IP privée dans le réseau virtuel. Les extraits de code suivants montrent comment configurer un Load Balancer interne pour un cluster AKS.

from azureml.core.compute.aks import AksUpdateConfiguration
from azureml.core.compute import AksCompute, ComputeTarget

# When you create an AKS cluster, you can specify Internal Load Balancer to be created with provisioning_config object
provisioning_config = AksCompute.provisioning_configuration(load_balancer_type = 'InternalLoadBalancer')

# Create the cluster
aks_target = ComputeTarget.create(workspace = ws,
                                name = aks_name,
                                provisioning_configuration = provisioning_config)

# Wait for the create process to complete
aks_target.wait_for_completion(show_output = True)

from azureml.core.compute import AksCompute, ComputeTarget
# Set the resource group that contains the AKS cluster and the cluster name
resource_group = 'myresourcegroup'
cluster_name = 'myexistingcluster'
# Change to the name of the subnet that contains AKS
subnet_name = "default"

# Attach the cluster to your workgroup. If the cluster has less than 12 virtual CPUs, use the following instead:
# attach_config = AksCompute.attach_configuration(resource_group = resource_group,
#                                         cluster_name = cluster_name,
#                                         cluster_purpose = AksCompute.ClusterPurpose.DEV_TEST)
attach_config = AksCompute.attach_configuration(resource_group = resource_group,
                                         cluster_name = cluster_name,
                                         load_balancer_type = 'InternalLoadBalancer', 
                                         load_balancer_subnet = subnet_name)
aks_target = ComputeTarget.attach(ws, 'myaks', attach_config)

# Wait for the attach process to complete
aks_target.wait_for_completion(show_output = True)

Détacher un cluster AKS

Pour détacher un cluster de votre espace de travail, utilisez l'une des méthodes suivantes :

aks_target.detach()

az ml computetarget detach -n myaks -g myresourcegroup -w myworkspace

Résolution des problèmes

Mettre à jour le cluster

Les mises à jour des composants Azure Machine Learning installés dans un cluster Azure Kubernetes Service doivent être appliquées manuellement.

Vous pouvez appliquer ces mises à jour en détachant le cluster de l’espace de travail Azure Machine Learning et en rattachant le cluster à l’espace de travail.

S’APPLIQUE À : SDK Python azureml v1

compute_target = ComputeTarget(workspace=ws, name=clusterWorkspaceName)
compute_target.detach()
compute_target.wait_for_completion(show_output=True)

Avant de pouvoir rattacher le cluster à votre espace de travail, vous devez d’abord supprimer toutes les ressources liées à azureml-fe. S’il n’existe aucun service actif dans le cluster, vous pouvez supprimer vos ressources liées à azureml-fe avec le code suivant.

kubectl delete sa azureml-fe
kubectl delete clusterrole azureml-fe-role
kubectl delete clusterrolebinding azureml-fe-binding
kubectl delete svc azureml-fe
kubectl delete svc azureml-fe-int-http
kubectl delete deploy azureml-fe
kubectl delete secret azuremlfessl
kubectl delete cm azuremlfeconfig

Si le protocole TLS est activé dans le cluster, vous devrez fournir le certificat et la clé privée TLS/SSL lors du rattachement du cluster.

S’APPLIQUE À : SDK Python azureml v1

attach_config = AksCompute.attach_configuration(resource_group=resourceGroup, cluster_name=kubernetesClusterName)

# If SSL is enabled.
attach_config.enable_ssl(
    ssl_cert_pem_file="cert.pem",
    ssl_key_pem_file="key.pem",
    ssl_cname=sslCname)

attach_config.validate_configuration()

compute_target = ComputeTarget.attach(workspace=ws, name=args.clusterWorkspaceName, attach_configuration=attach_config)
compute_target.wait_for_completion(show_output=True)

Si vous n’avez plus le certificat et la clé privée TLS/SSL, ou si vous utilisez un certificat généré par Azure Machine Learning, vous pouvez récupérer les fichiers avant de détacher le cluster en vous connectant au cluster avec kubectl et en extrayant le secret azuremlfessl.

kubectl get secret/azuremlfessl -o yaml

Échecs de service web

De nombreuses défaillances de services web dans AKS peuvent être déboguées en se connectant au cluster avec kubectl. Pour obtenir le kubeconfig.json d’un cluster AKS, exécutez la commande suivante :

S’APPLIQUE À : Extension ml Azure CLI v1

az aks get-credentials -g <rg> -n <aks cluster name>

Supprimer les ressources liées à azureml-fe

Une fois le cluster détaché, s’il n’y a aucun service actif dans le cluster, supprimez les ressources liées à azureml-fe avant de le rattacher :

kubectl delete sa azureml-fe
kubectl delete clusterrole azureml-fe-role
kubectl delete clusterrolebinding azureml-fe-binding
kubectl delete svc azureml-fe
kubectl delete svc azureml-fe-int-http
kubectl delete deploy azureml-fe
kubectl delete secret azuremlfessl
kubectl delete cm azuremlfeconfig

Les équilibreurs de charge ne doivent pas avoir d’adresses IP publiques

Lorsque vous tentez de créer ou d’attacher un cluster AKS, vous pouvez recevoir un message indiquant que la demande a été refusée parce que « les équilibreurs de charge ne doivent pas avoir d’adresses IP publiques ». Ce message est renvoyé lorsqu’un administrateur a appliqué une stratégie qui empêche l’utilisation d’un cluster AKS avec une adresse IP publique.

Pour résoudre ce problème, créez/attachez le cluster à l’aide des paramètres load_balancer_type et load_balancer_subnet. Pour plus d’informations, consultez Équilibreur de charge interne (adresse IP privée).

Étapes suivantes

• Utiliser Azure RBAC pour l’autorisation Kubernetes
• Comment et où déployer un modèle ?