Creare un cluster del servizio Azure Kubernetes e collegarlo con v1

SI APPLICA A:SDK Azure Machine Learning v1 per Python

SI APPLICA A:estensione ML dell'interfaccia della riga di comando di Azure v1

Azure Machine Learning può distribuire modelli di Machine Learning sottoposti a training nel servizio Azure Kubernetes. È tuttavia prima necessario creare un cluster del servizio Azure Kubernetes dall'area di lavoro di Azure Machine Learning o collegare un cluster del servizio Azure Kubernetes esistente. Questo articolo fornisce informazioni sulla creazione e sul collegamento di un cluster.

Prerequisiti

• Un'area di lavoro di Azure Machine Learning. Per ulteriori informazioni, vedere Creare un'area di lavoro di Azure Machine Learning.

• L'estensione dell'interfaccia della riga di comando (v1) di Azure per il servizio Machine Learning, Azure Machine Learning Python SDK, o l'estensione Azure Machine Learning Visual Studio Code.

  Importante

  Alcuni comandi dell'interfaccia della riga di comando (CLI) di Azure in questo articolo usano l'estensione azure-cli-ml, o v1, per Azure Machine Learning. Il supporto per l'interfaccia della riga di comando v1 è terminato il 30 settembre 2025. Microsoft non fornirà più supporto tecnico o aggiornamenti per questo servizio. I flussi di lavoro esistenti che usano l'interfaccia della riga di comando v1 continueranno a funzionare dopo la data di fine del supporto. Tuttavia, potrebbero essere esposti a rischi per la sicurezza o a modifiche di rilievo nel caso di cambiamenti dell'architettura del prodotto.

  È consigliabile passare all'estensione ml, o v2, il prima possibile. Per altre informazioni sull'estensione v2, vedere Estensione dell'interfaccia della riga di comando di Azure Machine Learning e Python SDK v2.

• Se si prevede di usare una rete virtuale di Azure per proteggere la comunicazione tra l'area di lavoro di Azure Machine Learning e il cluster del servizio Azure Kubernetes, l'area di lavoro e le risorse associate (archiviazione, insieme di credenziali delle chiavi, Registro Azure Container) devono presentare endpoint privati o endpoint di servizio nella stessa rete virtuale della rete virtuale del cluster del servizio Azure Kubernetes. Seguire l'esercitazione intitolata "creare un'area di lavoro sicura" per aggiungere tali endpoint privati o endpoint di servizio alla VNET.

Limitazioni

• Un servizio Azure Kubernetes può essere creato o collegato solo come singola destinazione di calcolo nell'area di lavoro di Azure Machine Learning. Non sono supportati più allegati per un calcolo del servizio Azure Kubernetes.

• Se è necessario che nel cluster sia distribuito un Load Balancer Standard (SLB) anziché un Load Balancer di base (BLB), creare un cluster nel portale del servizio Azure Kubernetes/CLI/SDK e quindi collegarlo all'area di lavoro di Azure Machine Learning.

• Se si dispone di una politica di Azure che limita la creazione di indirizzi IP pubblici, la creazione del cluster AKS non riesce. Il servizio Azure Kubernetes richiede un indirizzo IP pubblico per il traffico in uscita. L'articolo sul traffico in uscita fornisce anche materiale sussidiario per bloccare il traffico in uscita dal cluster tramite l'indirizzo IP pubblico, tranne che per alcuni nomi di dominio completi. Esistono 2 modi per abilitare un indirizzo IP pubblico:

  • Il cluster può usare l'IP pubblico creato per impostazione predefinita con BLB, SLB o
  • Il cluster può essere creato senza un IP pubblico, mentre un IP pubblico è configurato con un firewall con una route definita dall'utente. Per altre informazioni, vedere Personalizzare l'uscita del cluster con una route definita dall'utente.

  Il piano di controllo di Azure Machine Learning non comunica con questo indirizzo IP pubblico. Comunica con il piano di controllo del servizio Azure Kubernetes per le distribuzioni.

• Per collegare un cluster del servizio Azure Kubernetes, all'entità servizio o all'utente che esegue l'operazione deve essere assegnato il ruolo Proprietario o Collaboratore del controllo degli accessi in base al ruolo di Azure nel gruppo di risorse di Azure che contiene il cluster. All'entità servizio o all'utente deve essere assegnato anche il ruolo di amministratore del cluster del servizio Azure Kubernetes per il cluster.

• Se si collega un cluster del servizio Azure Kubernetes, con un intervallo IP autorizzato abilitato per accedere al server API, abilitare gli intervalli IP del piano di controllo di Azure Machine Learning per il cluster del servizio Azure Kubernetes. Il piano di controllo di Azure Machine Learning viene distribuito nelle diverse aree associate e distribuisce pod di inferenza nel cluster del servizio Azure Kubernetes. Senza l'accesso al server API, i pod di inferenza non possono essere distribuiti. Quando si abilitano gli intervalli IP in un cluster del servizio Azure Kubernetes, usare gli intervalli IP per entrambe le aree associate.

  Gli intervalli IP autorizzati funzionano solo con Load Balancer Standard.

• Se si vuole usare un cluster del servizio Azure Kubernetes privato (usando collegamento privato di Azure), è prima necessario creare il cluster e quindi collegarlo all'area di lavoro. Per altre informazioni, vedere Creare un cluster privato del servizio Azure Kubernetes.

• L'utilizzo di un nome di dominio completo (FQDN) pubblico con un cluster del servizio Azure Kubernetes privatonon è supportato con Azure Machine Learning.

• Il nome della risorsa di calcolo per il cluster del servizio Azure Kubernetes DEVE essere univoco nell'area di lavoro di Azure Machine Learning. Può includere lettere, cifre e trattini. Deve iniziare con una lettera, terminare con una lettera o una cifra e avere una lunghezza compresa tra 3 e 24 caratteri.

• Se si intende distribuire modelli nei nodi GPU o FPGA (o in uno SKU specifico), è necessario creare un cluster con lo SKU specifico. La creazione di un pool di nodi secondario in un cluster esistente e la distribuzione di modelli nel pool di nodi secondario non sono supportate.

• Quando si crea o si collega un cluster, è possibile selezionare se creare il cluster per sviluppo-test o produzione. Se si vuole creare un cluster del servizio Azure Kubernetes per lo sviluppo, la convalida e il test invece che per la produzione, impostare lo scopo del cluster su sviluppo-test. Se non si specifica lo scopo del cluster, viene creato un cluster di produzione .

  Importante

  Un cluster di test di sviluppo non è adatto per il traffico a livello di produzione e potrebbe aumentare i tempi di inferenza. I cluster di sviluppo/test non garantiscono anche la tolleranza di errore.

• Quando si crea o si collega un cluster, se il cluster viene usato per la produzione, deve contenere almeno 3 nodi. Un cluster di sviluppo-test deve contenere almeno 1 nodo.

• Azure Machine Learning SDK non supporta il ridimensionamento di un cluster AKS. Per ridimensionare i nodi nel cluster, usare l'interfaccia utente del cluster del servizio Azure Kubernetes in studio di Azure Machine Learning. È possibile modificare solo il conteggio dei nodi, non le dimensioni della macchina virtuale del cluster. Per altre informazioni sul ridimensionamento dei nodi in un cluster del servizio Azure Kubernetes, vedere gli articoli seguenti:

  • Ridimensionare manualmente il numero dei nodi in un cluster del servizio Azure Kubernetes
  • Configurare la scalabilità automatica del cluster nel servizio Azure Kubernetes

• Non aggiornare direttamente il cluster usando una configurazione YAML. Mentre i servizi Azure Kubernetes supportano gli aggiornamenti tramite la configurazione YAML, le distribuzioni di Azure Machine Learning sostituiscono le modifiche. Gli unici due campi YAML non sovrascritti sono limiti di richiesta e cpu e memoria.

• La creazione di un cluster del servizio Azure Kubernetes con l'interfaccia utente, l'SDK o l'interfaccia della riga di comando di studio di Azure Machine Learning non è idempotente. Il tentativo di creare di nuovo la risorsa genera un errore che indica che esiste già un cluster con lo stesso nome.

  • Anche l'uso di un modello di Azure Resource Manager e della risorsa Microsoft.MachineLearningServices/workspaces/computes per creare un cluster del servizio Azure Kubernetes non è idempotente. Se si tenta di usare di nuovo il modello per aggiornare una risorsa già esistente, viene visualizzato lo stesso errore.

Versione del servizio Azure Kubernetes

Il servizio Azure Kubernetes consente di creare un cluster usando varie versioni di Kubernetes. Per altre informazioni sulle versioni disponibili, vedere Versioni di Kubernetes supportate nel servizio Azure Kubernetes.

Quando si crea un cluster del servizio Azure Kubernetes usando uno dei metodi seguenti, non è possibile scegliere la versione del cluster creato:

• Lo studio di Azure Machine Learning o la sezione relativa ad Azure Machine Learning del portale di Azure.
• Estensione di Machine Learning per l'interfaccia della riga di comando di Azure.
• Azure Machine Learning SDK.

Con questi metodi di creazione di un cluster del servizio Azure Kubernetes viene usata la versione predefinita del cluster. La versione predefinita cambia nel tempo man mano che diventano disponibili nuove versioni di Kubernetes.

Quando si collega un cluster del servizio Azure Kubernetes esistente, è possibile usare tutte le versioni del servizio Azure Kubernetes attualmente supportate.

Versioni disponibili e predefinite

Per trovare le versioni del servizio Azure Kubernetes disponibili e predefinite, usare il comando az aks get-versions dell'interfaccia della riga di comando di Azure. Ad esempio, il comando seguente restituisce le versioni disponibili nell'area Stati Uniti occidentali:

az aks get-versions -l westus -o table

L'output di questo comando è simile al testo seguente:

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

Per trovare la versione predefinita usata durante la creazione di un cluster tramite Azure Machine Learning, è possibile usare il parametro --query per selezionare la versione predefinita:

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

L'output di questo comando è simile al testo seguente:

Result
--------
1.16.13

Se si vuole controllare a livello di codice le versioni disponibili, usare l'API REST Client del servizio contenitore - Elenca agenti di orchestrazione. Per trovare le versioni disponibili, esaminare le voci in cui orchestratorType è Kubernetes. Le voci orchestrationVersion associate contengono le versioni disponibili che è possibile collegare all'area di lavoro.

Per trovare la versione predefinita usata durante la creazione di un cluster tramite Azure Machine Learning, cercare la voce dove orchestratorType è Kubernetes e default è true. Il valore orchestratorVersion associato corrisponde alla versione predefinita. Il frammento JSON seguente mostra una voce di esempio:

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

Creare un nuovo cluster del servizio Azure Kubernetes

Tempo stimato: circa 10 minuti.

La creazione o il collegamento di un cluster del servizio Azure Kubernetes è un'operazione che viene eseguita una volta sola per l'area di lavoro. È possibile riutilizzare questo cluster per più distribuzioni. Se si elimina il cluster o il gruppo di risorse che lo contiene, per eseguire la distribuzione successiva sarà necessario creare un nuovo cluster. È possibile avere più cluster del servizio Azure Kubernetes collegati all'area di lavoro.

L'esempio seguente illustra come creare un nuovo cluster del servizio Azure Kubernetes usando l'SDK e l'interfaccia della riga di comando:

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

Collegare un cluster del servizio Azure Kubernetes esistente

Tempo stimato: circa cinque minuti.

Se nella sottoscrizione di Azure è già presente un cluster del servizio Azure Kubernetes, è possibile usarlo con l'area di lavoro.

Per altre informazioni sulla creazione di un cluster del servizio Azure Kubernetes tramite l'interfaccia della riga di comando di Azure o il portale, vedere gli articoli seguenti:

• Creare un cluster del servizio Azure Kubernetes (interfaccia della riga di comando)
• Creare un cluster del servizio Azure Container: (portale)
• Creare un cluster del servizio Azure Kubernetes (modello ARM nei modelli di avvio rapido di Azure)

L'esempio seguente illustra come collegare un cluster del servizio Azure Kubernetes esistente all'area di lavoro:

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

Creare o collegare un cluster del servizio Azure Kubernetes con terminazione TLS

Durante la creazione o il collegamento di un cluster del servizio Azure Kubernetes, è possibile abilitare la terminazione TLS con gli oggetti di configurazione AksCompute.provisioning_configuration() e AksCompute.attach_configuration(). Entrambi i metodi restituiscono un oggetto di configurazione con un metodo enable_ssl ed è possibile usare il metodo enable_ss per abilitare TLS.

Nell'esempio seguente viene illustrato come abilitare la terminazione TLS con la generazione e la configurazione automatica dei certificati TLS usando il certificato Microsoft.

SI APPLICA A:SDK Azure Machine Learning v1 per Python

   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'esempio seguente illustra come abilitare la terminazione TLS con certificato e nome di dominio personalizzato. Con un dominio personalizzato e un certificato, è necessario aggiornare il record DNS in modo che punti all'indirizzo IP dell'endpoint di assegnazione dei punteggi, vedere Aggiornare il DNS

SI APPLICA A:SDK Azure Machine Learning v1 per Python

   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")

Creare o collegare un cluster del servizio Azure Kubernetes per usare il servizio di bilanciamento del carico interno con IP privato

Quando si crea o si collega un cluster del servizio Azure Kubernetes, è possibile configurare il cluster per l'uso di un servizio di bilanciamento del carico interno. Con un servizio di bilanciamento del carico interno, l'assegnazione dei punteggi agli endpoint per le distribuzioni nel servizio Azure Kubernetes usa un indirizzo IP privato all'interno della rete virtuale. I frammenti di codice seguenti illustrano come configurare un servizio di bilanciamento del carico interno per un cluster del servizio Azure Kubernetes.

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)

Rimuovere un cluster del servizio Azure Kubernetes

Per rimuovere un cluster dall'area di lavoro, usare uno dei metodi seguenti:

aks_target.detach()

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

Risoluzione dei problemi

Aggiornare il cluster

Gli aggiornamenti ai componenti di Azure Machine Learning installati in un cluster del servizio Azure Kubernetes devono essere applicati manualmente.

È possibile applicare questi aggiornamenti rimuovendo il cluster dall'area di lavoro di Azure Machine Learning e ricollegandolo.

SI APPLICA A:SDK Azure Machine Learning v1 per Python

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

Prima di poter ricollegare il cluster all'area di lavoro, è necessario prima eliminare tutte le risorse di azureml-fe correlate. Se nel cluster non è presente alcun servizio attivo, è possibile eliminare le azureml-fe risorse correlate con il codice seguente.

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

Se TLS è abilitato nel cluster, è necessario specificare il certificato TLS/SSL e la chiave privata quando si ricollega il cluster.

SI APPLICA A:SDK Azure Machine Learning v1 per Python

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)

Se non si dispone più del certificato TLS/SSL e della chiave privata oppure si usa un certificato generato da Azure Machine Learning, è possibile recuperare i file prima di scollegare il cluster connettendosi al cluster usando kubectl e recuperando il segreto azuremlfessl.

kubectl get secret/azuremlfessl -o yaml

Errori del servizio Web

È possibile eseguire il debug di molti errori del servizio Web nel servizio Azure Kubernetes connettendosi al cluster tramite kubectl. È possibile ottenere kubeconfig.json per un cluster del servizio Azure Kubernetes eseguendo

SI APPLICA A:estensione ML dell'interfaccia della riga di comando di Azure v1

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

Eliminare le risorse correlate ad azureml-fe

Dopo aver scollegato il cluster, se non è presente un servizio attivo nel cluster, eliminare le azureml-fe risorse correlate prima di collegarsi di nuovo:

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

I servizi di bilanciamento del carico non devono avere indirizzi IP pubblici

Quando si tenta di creare o collegare un cluster del servizio Azure Kubernetes, è possibile che venga visualizzato un messaggio che indica che la richiesta viene negata perché "Load Balancers non deve avere indirizzi IP pubblici". Questo messaggio viene restituito quando un amministratore ha applicato un criterio che impedisce l'uso di un cluster del servizio Azure Kubernetes con un indirizzo IP pubblico.

Per risolvere questo problema, creare/collegare il cluster usando i parametri load_balancer_type e load_balancer_subnet. Per altre informazioni, vedere Bilanciamento del carico interno (IP privato).

Passaggi successivi

• Usare il controllo degli accessi in base al ruolo di Azure per l'autorizzazione con Kubernetes
• Come e dove distribuire un modello