Partilhar via

Criar e anexar um cluster do Serviço Kubernetes do Azure com v1

  • Artigo

APLICA-SE A: Python SDK azureml v1

APLICA-SE A: Azure CLI ml extension v1

Importante

Este artigo mostra como usar a CLI e o SDK v1 para criar ou anexar um cluster do Serviço Kubernetes do Azure, que é considerado um recurso herdado agora. Para anexar o cluster do Serviço Kubernetes do Azure usando a abordagem recomendada para v2, consulte Introdução ao destino de computação do Kubernetes na v2.

O Azure Machine Learning pode implantar modelos treinados de aprendizado de máquina no Serviço Kubernetes do Azure. No entanto, você deve primeiro criar um cluster do Serviço Kubernetes do Azure (AKS) a partir do seu espaço de trabalho do Azure Machine Learning ou anexar um cluster AKS existente. Este artigo fornece informações sobre como criar e anexar um cluster.

Pré-requisitos

  • Uma área de trabalho do Azure Machine Learning. Para obter mais informações, consulte Criar um espaço de trabalho do Azure Machine Learning.

  • A extensão da CLI do Azure (v1) para o serviço de Aprendizado de Máquina, o SDK Python do Azure Machine Learning ou a extensão de Código do Azure Machine Learning Visual Studio.

    Importante

    Alguns dos comandos da CLI do Azure neste artigo usam a extensão , ou v1, para o azure-cli-mlAzure Machine Learning. O suporte para a extensão v1 terminará em 30 de setembro de 2025. Você poderá instalar e usar a extensão v1 até essa data.

    Recomendamos que você faça a transição para a mlextensão , ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, consulte Extensão CLI do Azure ML e Python SDK v2.

  • Se você planeja usar uma Rede Virtual do Azure para proteger a comunicação entre seu espaço de trabalho do Azure Machine Learning e o cluster AKS, seu espaço de trabalho e seus recursos associados (armazenamento, cofre de chaves, Registro de Contêiner do Azure) devem ter pontos de extremidade privados ou pontos de extremidade de serviço na mesma VNET que a VNET do cluster AKS. Siga o tutorial : crie um espaço de trabalho seguro para adicionar esses pontos de extremidade privados ou pontos de extremidade de serviço à sua VNET.

Limitações

  • Só é possível criar ou anexar um AKS como um destino de computação individual na área de trabalho do Azure Machine Learning. Não são suportados vários anexos para um AKS.

  • Se precisar de um Balanceador de Carga Standard(SLB) implementado no cluster em vez de um Balanceador de Carga Básico (BLB) , crie um cluster no portal do AKS/CLI/SDK e, em seguida, anexe-o à área de trabalho do Azure Machine Learning.

  • Se tiver uma política do Azure Policy que restrinja a criação de endereços IP públicos, a criação do cluster do AKS falhará. O AKS requer um IP Público para o tráfego de saída. O artigo relativo ao tráfego de saída também disponibiliza orientações para bloquear o tráfego de saída do cluster através do IP Público, exceto alguns nomes de domínio completamente qualificados. Existem duas formas de ativar um IP Público:

    O plano de controlo do Azure Machine Learning não comunica com este IP Público. Comunica com o plano de controlo do AKS para implementações.

  • Para anexar um cluster AKS, a entidade de serviço/usuário que executa a operação deve receber a função de controle de acesso baseado em função do Azure (Azure RBAC) Proprietário ou contribuidor no grupo de recursos do Azure que contém o cluster. A entidade de serviço/usuário também deve receber a Função de Administrador do Cluster de Serviço do Kubernetes do Azure no cluster.

  • Se anexar um cluster do AKS, que tem um intervalo de IP autorizado ativado para aceder ao servidor de API, ative os intervalos de IP do plano de controlo do Azure Machine Learning para o cluster do AKS. O plano de controlo do Azure Machine Learning é implementado transversalmente em regiões emparelhadas e implementa pods de inferência no cluster do AKS. Sem acesso ao servidor de API, os pods de inferência não podem ser implementados. Utilize os intervalos de IP para ambas as regiões emparelhadas quando ativar os intervalos de IP num cluster do AKS.

    Os intervalos de IP autorizados só funcionam com o Balanceador de Carga Standard.

  • Se quiser utilizar um cluster privado do AKS (mediante a utilização do Azure Private Link), primeiro tem de criar o cluster e, em seguida, anexá-lo à área de trabalho. Para obter mais informações, veja Criar um cluster do Azure Kubernetes Service privado.

  • A utilização de um nome de domínio completamente qualificado (FQDN) com um cluster do AKS privadonão é suportada com o Azure Machine Learning.

  • O nome de computação do cluster do AKS TEM DE ser exclusivo na área de trabalho do Azure Machine Learning. Pode incluir letras, dígitos e traços. Tem de começar com uma letra, terminar com uma letra ou dígito e ter entre 3 e 24 carateres de comprimento.

  • Se você quiser implantar modelos em nós de GPU ou nós de FPGA (ou qualquer SKU específico), deverá criar um cluster com a SKU específica. Não existe suporte para criar um conjunto de nós secundário num cluster existente e implementar modelos no conjunto de nós secundário.

  • Ao criar ou anexar um cluster, pode selecionar se pretende criar o cluster para dev/test ou produção. Se pretender criar um cluster do AKS para desenvolvimento, validação e testes em vez de produção, defina o objetivo do cluster como dev/test. Se não especificar a finalidade do cluster, é criado um cluster de produção.

    Importante

    Um cluster de desenvolvimento e teste não é adequado para o tráfego de nível de produção e pode aumentar os tempos de inferência. Os clusters de desenvolvimento/teste também não garantem tolerância a falhas.

  • Ao criar ou anexar um cluster, se o cluster for usado para produção, ele deverá conter pelo menos 3 nós. Os clusters de dev/test têm de conter, pelo menos, um nó.

  • O SDK do Azure Machine Learning não oferece suporte para o dimensionamento de clusters do AKS. Para dimensionar os nós no cluster, utilize a IU do cluster do AKS no estúdio do Azure Machine Learning. Só pode alterar a contagem de nós e não o tamanho da VM do cluster. Para obter mais informações sobre como dimensionar os nós num cluster do AKS, veja os seguintes artigos:

  • Não atualize diretamente o cluster mediante a utilização de uma configuração do YAML. Embora o Azure Kubernetes Service suporte atualizações através da configuração do YAML, as implementações do Azure Machine Learning irão substituir as suas alterações. Os únicos dois campos do YAML que não serão substituídos são os limites de pedidos e a CPU e a memória.

  • Criar um cluster AKS usando a interface do usuário, SDK ou extensão CLI do estúdio Azure Machine Learning não é idempotente. Tentar criar o recurso novamente resultará num erro de que já existe um cluster com o mesmo nome.

Versão do Azure Kubernetes Service

O Serviço Kubernetes do Azure permite que você crie um cluster usando uma variedade de versões do Kubernetes. Para obter mais informações sobre as versões disponíveis, consulte Versões do Kubernetes suportadas no Serviço Kubernetes do Azure.

Ao criar um cluster do Serviço Kubernetes do Azure usando um dos seguintes métodos, você não tem uma escolha na versão do cluster que é criado:

  • Estúdio do Azure Machine Learning ou a seção Azure Machine Learning do portal do Azure.
  • Extensão de Aprendizado de Máquina para CLI do Azure.
  • SDK do Azure Machine Learning.

Esses métodos de criação de um cluster AKS usam a versão padrão do cluster. A versão padrão muda com o tempo à medida que novas versões do Kubernetes ficam disponíveis.

Ao anexar um cluster AKS existente, suportamos todas as versões AKS atualmente suportadas.

Importante

O Serviço Kubernetes do Azure usa o driver Blobfuse FlexVolume para as versões <=1.16 e o driver Blob CSI para as versões >=1.17. Portanto, é importante reimplantar ou atualizar o serviço Web após a atualização do cluster para implantar o método blobfuse correto para a versão do cluster.

Nota

Pode haver casos de borda em que você tenha um cluster mais antigo que não é mais suportado. Nesse caso, a operação de anexação retornará um erro e listará as versões suportadas atualmente.

Você pode anexar versões de visualização . A funcionalidade de visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. O suporte para a utilização de versões de pré-visualização pode ser limitado. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Versões disponíveis e padrão

Para localizar as versões AKS disponíveis e padrão, use o comando da CLI do Azure az aks get-versions. Por exemplo, o comando a seguir retorna as versões disponíveis na região Oeste dos EUA:

az aks get-versions -l westus -o table

A saída deste comando é semelhante ao seguinte texto:

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

Para localizar a versão padrão usada ao criar um cluster por meio do Aprendizado de Máquina do Azure, você pode usar o --query parâmetro para selecionar a versão padrão:

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

A saída deste comando é semelhante ao seguinte texto:

Result
--------
1.16.13

Se você quiser verificar programaticamente as versões disponíveis, use a API REST do Container Service Client - List Orchestrators. Para encontrar as versões disponíveis, veja as entradas onde orchestratorType está Kubernetes. As entradas associadas orchestrationVersion contêm as versões disponíveis que podem ser anexadas ao seu espaço de trabalho.

Para localizar a versão padrão usada ao criar um cluster por meio do Aprendizado de Máquina do Azure, localize a entrada onde orchestratorType está Kubernetes e default está true. O valor associado orchestratorVersion é a versão padrão. O trecho JSON a seguir mostra uma entrada de exemplo:

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

Criar um novo cluster AKS

Estimativa de tempo: Aproximadamente 10 minutos.

Criar ou anexar um cluster AKS é um processo único para o seu espaço de trabalho. Você pode reutilizar esse cluster para várias implantações. Se você excluir o cluster ou o grupo de recursos que o contém, deverá criar um novo cluster na próxima vez que precisar implantar. Você pode ter vários clusters AKS anexados ao seu espaço de trabalho.

O exemplo a seguir demonstra como criar um novo cluster AKS usando o SDK e a CLI:

APLICA-SE A: Python SDK azureml v1

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)

Para obter mais informações sobre as classes, métodos e parâmetros usados neste exemplo, consulte os seguintes documentos de referência:

Anexar um cluster AKS existente

Estimativa de tempo: Aproximadamente 5 minutos.

Se você já tiver o cluster AKS em sua assinatura do Azure, poderá usá-lo com seu espaço de trabalho.

Gorjeta

O cluster AKS existente pode estar em uma região do Azure diferente do seu espaço de trabalho do Azure Machine Learning.

Aviso

Não crie vários anexos simultâneos para o mesmo cluster AKS. Por exemplo, anexar um cluster AKS a um espaço de trabalho usando dois nomes diferentes ou anexar um cluster AKS a um espaço de trabalho diferente. Cada novo anexo quebrará o(s) anexo(s) existente(s) anterior(es) e causará erros imprevisíveis.

Se você quiser anexar novamente um cluster AKS, por exemplo, para alterar TLS ou outra definição de configuração de cluster, você deve primeiro remover o anexo existente usando AksCompute.detach().

Para obter mais informações sobre como criar um cluster AKS usando a CLI ou o portal do Azure, consulte os seguintes artigos:

O exemplo a seguir demonstra como anexar um cluster AKS existente ao seu espaço de trabalho:

APLICA-SE A: Python SDK azureml v1

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)

Para obter mais informações sobre as classes, métodos e parâmetros usados neste exemplo, consulte os seguintes documentos de referência:

Criar ou anexar um cluster AKS com terminação TLS

Ao criar ou anexar um cluster AKS, você pode habilitar a terminação TLS com objetos de configuração AksCompute.provisioning_configuration() e AksCompute.attach_configuration(). Ambos os métodos retornam um objeto de configuração que tem um método enable_ssl e você pode usar enable_ssl método para habilitar o TLS.

O exemplo a seguir mostra como habilitar a terminação TLS com geração e configuração automática de certificado TLS usando o certificado da Microsoft nos bastidores.

APLICA-SE A: Python SDK 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")

O exemplo a seguir mostra como habilitar a terminação TLS com certificado personalizado e nome de domínio personalizado. Com domínio e certificado personalizados, você deve atualizar seu registro DNS para apontar para o endereço IP do ponto de extremidade de pontuação, consulte Atualizar seu DNS

APLICA-SE A: Python SDK 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")

Nota

Para obter mais informações sobre como proteger a implantação de modelo no cluster AKS, consulte Usar TLS para proteger um serviço Web por meio do Azure Machine Learning

Criar ou anexar um cluster AKS para usar o Balanceador de Carga Interno com IP privado

Ao criar ou anexar um cluster AKS, você pode configurar o cluster para usar um Balanceador de Carga Interno. Com um Balanceador de Carga Interno, a pontuação de pontos de extremidade para suas implantações no AKS usará um IP privado dentro da rede virtual. Trechos de código a seguir mostram como configurar um Balanceador de Carga Interno para um cluster AKS.

APLICA-SE A: Python SDK azureml v1

Para criar um cluster AKS que usa um Balanceador de Carga Interno, use os load_balancer_type parâmetros e load_balancer_subnet :

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)

Importante

Se o cluster AKS estiver configurado com um Balanceador de Carga Interno, o uso de um certificado fornecido pela Microsoft não é suportado e você deve usar um certificado personalizado para habilitar o TLS.

Nota

Para obter mais informações sobre como proteger o ambiente de inferência, consulte Proteger um ambiente de inferência do Azure Machine Learning

Desanexar um cluster AKS

Para desanexar um cluster do seu espaço de trabalho, use um dos seguintes métodos:

Aviso

Usar o estúdio do Azure Machine Learning, SDK ou a extensão da CLI do Azure para aprendizado de máquina para desanexar um cluster AKS não exclui o cluster AKS. Para excluir o cluster, consulte Usar a CLI do Azure com AKS.

APLICA-SE A: Python SDK azureml v1

aks_target.detach()

Resolução de Problemas

Atualizar o cluster

As atualizações dos componentes do Azure Machine Learning instaladas em um cluster do Serviço Kubernetes do Azure devem ser aplicadas manualmente.

Você pode aplicar essas atualizações desanexando o cluster do espaço de trabalho do Azure Machine Learning e reanexando o cluster ao espaço de trabalho.

APLICA-SE A: Python SDK azureml v1

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

Antes de reanexar o cluster ao seu espaço de trabalho, você precisa primeiro excluir todos os azureml-fe recursos relacionados. Se não houver nenhum serviço ativo no cluster, você poderá excluir seus azureml-fe recursos relacionados com o código a seguir.

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 o TLS estiver habilitado no cluster, você precisará fornecer o certificado TLS/SSL e a chave privada ao reanexar o cluster.

APLICA-SE A: Python SDK 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)

Se você não tiver mais o certificado TLS/SSL e a chave privada, ou estiver usando um certificado gerado pelo Aprendizado de Máquina do Azure, poderá recuperar os arquivos antes de desanexar o cluster conectando-se ao cluster usando kubectl e recuperando o segredo azuremlfessl.

kubectl get secret/azuremlfessl -o yaml

Nota

O Kubernetes armazena os segredos no formato codificado em Base64. Você precisará Base64-decodificar os cert.pem e key.pem componentes dos segredos antes de fornecê-los para attach_config.enable_ssl.

Falhas de Webservice

Muitas falhas de serviço Web no AKS podem ser depuradas conectando-se ao cluster usando kubectlo . Você pode obter o kubeconfig.json para um cluster AKS executando

APLICA-SE A: Azure CLI ml extension v1

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

Depois de desanexar o cluster, se não houver nenhum serviço ativo no cluster, exclua os azureml-fe recursos relacionados antes de anexar novamente:

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

Os balanceadores de carga não devem ter IPs públicos

Ao tentar criar ou anexar um cluster AKS, você pode receber uma mensagem informando que a solicitação foi negada porque "Load Balancers não devem ter IPs públicos". Esta mensagem é retornada quando um administrador aplica uma política que impede o uso de um cluster AKS com um endereço IP público.

Para resolver esse problema, crie/anexe o cluster usando os load_balancer_type parâmetros e load_balancer_subnet . Para obter mais informações, consulte Balanceador de carga interno (IP privado).

Próximos passos