使用 v1 建立並連結 Azure Kubernetes Service 叢集

發行項
09/04/2024

重要

本文說明如何使用 CLI 和 SDK v1，建立或連結 Azure Kubernetes Service 叢集，這目前已視為是舊版功能。若要使用建議的 v2 方法連結 Azure Kubernetes Service 叢集，請參閱 v2 的 Kubernetes 計算目標簡介。

Azure Machine Learning 可以將定型的機器學習模型部署到 Azure Kubernetes Service。不過，您必須先從 Azure Machine Learning 工作區建立 Azure Kubernetes Service (AKS) 叢集，或連結現有的 AKS 叢集。本文提供建立和連結叢集的相關資訊。

必要條件

Azure Machine Learning 工作區。如需詳細資訊，請參閱建立 Azure Machine Learning 工作區。
適用於 Machine Learning 服務的 Azure CLI 延伸模組 (第 1 版)、Azure Machine Learning Python SDK 或 Azure Machine Learning Visual Studio Code 擴充功能。

重要

本文中的 Azure CLI 命令使用 azure-cli-ml 或 v1 (Azure Machine Learning 的擴充功能)。 v1 擴充功能的支援將於 2025 年 9 月 30 日終止。您將能安裝並使用 v1 擴充功能，直到該日期為止。

建議您在 2025 年 9 月 30 日之前轉換至 ml 或 v2 擴充功能。如需有關 v2 擴充功能的詳細資訊，請參閱 Azure ML CLI 擴充功能和 Python SDK v2。
如果您打算使用 Azure 虛擬網路來保護 Azure Machine Learning 工作區與 AKS 叢集之間的通訊，您的工作區及其相關聯的資源 (儲存體、金鑰保存庫Azure Container Registry) 必須在與 AKS 叢集 VNET 相同的 VNET 中擁有私人端點或服務端點。請遵循教學課程建立安全的工作區，將這些私人端點或服務端點新增至您的 VNET。

限制

AKS 只能建立或連結為 Azure Machine Learning 工作區的單一計算目標。不支援單一 AKS 的多個連結。
如果需要在叢集中部署 Standard Load Balancer (SLB) ，而不是 Basic Load Balancer (BLB) ，請在 AKS 入口網站/CLI/SDK 建立叢集，然後將其連結至 Azure Machine Learning 工作區。
如果您有會限制建立公用 IP 位址的 Azure 原則，AKS 叢集建立將會失敗。 AKS 需要公用 IP 來提供輸出流量。輸出流量一文也會提供指引，以透過公用 IP 鎖定來自叢集的輸出流量，但有幾個完整網域名稱除外。有 2 個方式可以啟用公用 IP：
- 叢集可以使用預設使用 BLB 或 SLB 建立的公用 IP，或者
- 叢集可以在不使用公用 IP 的情況下建立，然後使用具有使用者定義路由的防火牆來設定公用 IP。如需詳細資訊，請參閱透過使用者定義的路由自訂叢集輸出。
Azure Machine Learning 控制平面不會與此「公用 IP」通訊。它會與部署的 AKS 控制平面通訊。
若要連結 AKS 叢集，執行作業的服務主體/使用者必須在包含叢集的 Azure 資源群組上獲指派擁有者或參與者 Azure 角色型存取控制 (Azure RBAC) 角色。服務主體/使用者也必須獲指派叢集上的 Azure Kubernetes Service 叢集管理員角色。
如果連結 AKS 叢集，其已啟用「授權 IP」範圍以存取 API 伺服器，請為此 AKS 啟用 Azure Machine Learning 控制平面 IP 範圍。 Azure Machine Learning 控制平面會部署在配對的區域，並在 AKS 叢集部署推斷 Pod。如果沒有 API 伺服器的存取權，則無法部署推斷 Pod。在 AKS 叢集中啟用 IP 範圍時，請對這兩個配對區域使用該 IP 範圍。

授權的 IP 範圍僅適用於 Standard Load Balancer。
如果您想要使用私人 AKS 叢集 (使用 Azure Private Link)，您必須先建立叢集，然後將它連結至工作區。如需詳細資訊，請參閱建立私人 Azure Kubernetes Service 叢集。
Azure Machine learning 不支援使用公用完整網域名稱 (FQDN) 搭配私人 AKS 叢集。
AKS 叢集的計算名稱在 Azure Machine Learning 工作區中必須是唯一。它可以包含字母、數字和連字號。其開頭必須為字母，結尾必須是字母或數字，且長度必須介於 3 到 24 個字元之間。
如果您想要將模型部署至 GPU 節點或 FPGA 節點 (或任何特定 SKU)，則必須建立具有特定 SKU 的叢集。不支援在現有的叢集中建立次要節點集區，並在次要節點集區中部署模型。
建立或連結叢集時，您可以選取是否要建立用於開發/測試或生產的叢集。如果您想要建立用於開發、驗證和測試的 AKS 叢集，而不是生產，請將 [叢集用途] 設定為開發/測試。如果您未指定叢集用途，則會建立生產叢集。

重要

開發/測試叢集不適合用於生產層級的流量，可能會增加推斷時間。開發/測試叢集也不保證容錯。
建立或連結叢集時，如果叢集將用於生產，則必須至少包含 3 個節點。針對開發/測試叢集，它必須包含至少 1 個節點。
Azure Machine Learning SDK 不提供調整 AKS 叢集的支援。若要調整叢集中的節點，請在 Azure Machine Learning 工作室中使用您的 AKS 叢集的 UI。您只能變更節點計數，而無法變更叢集的 VM 大小。如需有關調整 AKS 叢集中節點的詳細資訊，請參閱下列文章：
- 手動調整 AKS 叢集中的節點計數
- 在 AKS 中設定叢集自動調整程式
請勿使用 YAML 設定直接更新叢集。雖然 Azure Kubernetes Services 支援透過 YAML 設定更新，但 Azure Machine Learning 部署將會覆寫您的變更。唯一不會覆寫的兩個 YAML 欄位是要求限制及 CPU 和記憶體。
使用 Azure Machine Learning 工作室 UI、SDK 或 CLI 擴充功能建立 AKS 叢集並不具等冪性。嘗試再次建立資源將會產生錯誤，指出已經存在具有相同名稱的叢集。
- 使用 Azure Resource Manager 範本和 Microsoft.MachineLearningServices/workspaces/computes 資源來建立 AKS 叢集也不具等冪性。如果您嘗試再次使用範本來更新現有的資源，將會收到相同的錯誤。

Azure Kubernetes Service 版本

Azure Kubernetes Service 可讓您使用各種 Kubernetes 版本來建立叢集。如需可用版本的詳細資訊，請參閱 Azure Kubernetes Service 中支援的 Kubernetes 版本。

使用下列其中一種方法建立 Azure Kubernetes Service 叢集時，您無法選擇建立的叢集版本 ：

Azure Machine Learning 工作室或 Azure 入口網站的 Azure Machine Learning 區段。
適用於 Azure CLI 的機器學習擴充功能。
Azure Machine Learning SDK。

建立 AKS 叢集的這些方法會使用叢集的預設版本。當新的 Kubernetes 版本可供使用時，預設版本會隨著時間變更。

連結現有的 AKS 叢集時，我們支援所有目前支援的 AKS 版本。

重要

Azure Kubernetes Service <=1.16 版使用 Blobfuse FlexVolume 驅動程式，而 >=1.17 版使用 Blob CSI 驅動程式。因此，請務必在叢集升級之後重新部署或更新 Web 服務，以便部署到叢集版本的正確 blobfuse 方法。

注意

在某些情況下，您可能會有已不再支援的較舊叢集的邊緣案例。在此情況下，連結作業會傳回錯誤並列出目前支援的版本。

您可以連結預覽版本。預覽功能是在沒有服務等級協定的情況下提供，不建議用於生產工作負載。可能不支援特定功能，或可能已經限制功能。對使用預覽版本的支援可能受到限制。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

可用和預設版本

若要尋找可用和預設的 AKS 版本，請使用 Azure CLI 命令 az aks get-versions。例如，下列命令會傳回美國西部區域中可用的版本：

az aks get-versions -l westus -o table

此命令的輸出類似下列文字：

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

若要尋找透過 Azure Machine Learning 建立叢集時所使用的預設版本，您可以使用 --query 參數來選取預設版本：

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

此命令的輸出類似下列文字：

Result
--------
1.16.13

如果您想要以程式設計方式檢查可用的版本，請使用容器服務用戶端 - 列出協調器 REST API。若要尋找可用的版本，請查看其中的 orchestratorType 為 Kubernetes 的項目。相關聯的 orchestrationVersion 項目包含可連結至工作區的可用版本。

若要尋找透過 Azure Machine Learning 建立叢集時所使用的預設版本，請尋找其中的 orchestratorType 為 Kubernetes 和 default 為 true 的項目。相關聯的 orchestratorVersion 值是預設版本。下列 JSON 程式碼片段顯示一個範例項目：

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

建立新的 AKS 叢集

估計時間：約 10 分鐘。

建立或連結 AKS 叢集是工作區的一次性程序。您可以重複使用此叢集進行多個部署。如果刪除叢集或包含該叢集的資源群組，則必須在下次需要部署時建立新的叢集。您可以將多個 AKS 叢集連結至您的工作區。

下列範例示範如何使用 SDK 和 CLI 來建立新的 AKS 叢集：

適用於：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)

如需此範例中所使用的類別、方法和參數的詳細資訊，請參閱下列參考文件：

適用於：Azure CLI ml 延伸模組 v1

az ml computetarget create aks -n myaks

如需詳細資訊，請參閱 az ml computetarget create aks 參考。

連結現有的 AKS 叢集

估計時間：約 5 分鐘。

如果您的 Azure 訂用帳戶中已經有 AKS 叢集，您可以使用它搭配您的工作區。

提示

現有的 AKS 叢集可以位於 Azure Machine Learning 工作區以外的 Azure 區域中。

警告

請勿將多個同時連結建立至同一個 AKS 叢集。例如，使用兩個不同的名稱將單一 AKS 叢集連結至工作區，或單一 AKS 叢集連結至不同的工作區。每個新連結會中斷之前的現有連結，並造成無法預期的錯誤。

如果您想要重新連結 AKS 叢集 (例如，為了變更 TLS 或其他叢集設定)，必須先使用 AksCompute.detach() 移除現有的連結。

如需使用 Azure CLI 或入口網站建立 AKS 叢集的詳細資訊，請參閱下列文章：

下列範例示範如何將現有的 AKS 叢集連結至您的工作區：

適用於：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)

如需此範例中所使用的類別、方法和參數的詳細資訊，請參閱下列參考文件：

適用於：Azure CLI ml 延伸模組 v1

若要使用 CLI 連結現有的叢集，您需要取得現有叢集的資源識別碼。若要取得此值，請使用下列命令。將 myexistingcluster 取代為您的 AKS 叢集名稱。將 myresourcegroup 取代為包含叢集的資源群組：

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

此命令會傳回類似下列文字的值：

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

若要將現有的叢集連結至您的工作區，請使用下列命令。將 aksresourceid 取代為上一個命令傳回的值。將 myresourcegroup 取代為包含您的工作區的資源群組。將 myworkspace 取代為您的工作區名稱。

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

如需詳細資訊，請參閱 az ml computetarget attach aks 參考。

使用 TLS 終止建立或連結 AKS 叢集

當您建立或連結 AKS 叢集時，您可以使用 AksCompute.provisioning_configuration() 和 AksCompute.attach_configuration() 設定物件來啟用 TLS 終止。這兩種方法都會傳回具有 enable_ssl 方法的設定物件，而您可以使用 enable_ssl 方法來啟用 TLS。

下列範例示範如何在幕後使用 Microsoft 憑證，透過自動 TLS 憑證產生和設定啟用 TLS 終止。

適用於：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")

下列範例顯示如何使用自訂憑證和自訂網域名稱來啟用 TLS 終止。使用自訂網域和憑證時，您必須更新您的 DNS 記錄以指向評分端點的 IP 位址，請參閱更新您的 DNS

適用於：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")

注意

如需如何在 AKS 叢集上保護模型部署的詳細資訊，請參閱使用 TLS 透過 Azure Machine Learning 保護 Web 服務的安全

建立或連結 AKS 叢集以使用 Internal Load Balancer 搭配私人 IP

建立或連結 AKS 叢集時，您可以將叢集設定為使用 Internal Load Balancer。使用 Internal Load Balancer 時，您部署至 AKS 的評分端點將會使用虛擬網路內的私人 IP。下列程式碼片段示範如何設定 AKS 叢集的 Internal Load Balancer。

建立
附加

適用於：Python SDK azureml v1

若要建立使用內部負載平衡器的 AKS 叢集，請使用 load_balancer_type 和 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)

適用於：Python SDK azureml v1

若要連結 AKS 叢集並使用內部負載平衡器 (沒有叢集的公用 IP)，請使用 load_balancer_type 和 load_balancer_subnet 參數：

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)

重要

如果您的 AKS 叢集設定為內部負載平衡器，則不支援使用 Microsoft 提供的憑證，而且您必須使用自訂憑證來啟用 TLS。

注意

如需如何保護推斷環境的詳細資訊，請參閱保護 Azure Machine Learning 推斷環境

中斷連結 AKS 叢集

若要從您的工作區中斷連結叢集，請使用下列其中一種方法：

警告

使用 Azure Machine Learning 工作室、SDK 或適用於機器學習的 Azure CLI 擴充功能來中斷連結 AKS 叢集，並不會刪除 AKS 叢集。若要刪除叢集，請參閱使用 Azure CLI 搭配 AKS。

適用於：Python SDK azureml v1

aks_target.detach()

適用於：Azure CLI ml 延伸模組 v1

若要將現有的叢集與您的工作區中斷連結，請使用下列命令。將 myaks 取代為 AKS 叢集連結至工作區的名稱。將 myresourcegroup 取代為包含您的工作區的資源群組。將 myworkspace 取代為您的工作區名稱。

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

疑難排解

更新叢集

對安裝在 Azure Kubernetes Service 叢集中 Azure Machine Learning 元件的更新必須手動套用。

您可以將叢集從 Azure Machine Learning 工作區中斷連結，然後將叢集重新連結到工作區，以套用這些更新。

適用於：Python SDK azureml v1

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

您必須先刪除任何 azureml-fe 相關資源，才能將叢集重新連結至工作區。如果叢集中沒有作用中的服務，您可以使用下列程式碼刪除 azureml-fe 相關資源。

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

如果叢集中已啟用 TLS，則在重新連結叢集時，您將需要提供 TLS/SSL 憑證和私密金鑰。

適用於：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)

如果您不再有 TLS/SSL 憑證和私密金鑰，或您使用 Azure Machine Learning 產生的憑證，則可以使用 kubectl 來連接到叢集並擷取密碼 azuremlfessl，以便在中斷連結叢集之前擷取檔案。

kubectl get secret/azuremlfessl -o yaml

注意

Kubernetes 會以 Base64 編碼格式儲存密碼。您將需要使用 Base64 來解碼密碼的 cert.pem 和 key.pem 元件，再將其提供給 attach_config.enable_ssl。

Web 服務失敗

AKS 中的許多 Web 服務失敗都可以藉由使用 kubectl 連線到叢集來偵錯。您可以藉由執行以下來取得 AKS 叢集的 kubeconfig.json

適用於：Azure CLI ml 延伸模組 v1

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

中斷連結叢集之後，如果叢集中沒有任何作用中的服務，請先刪除 azureml-fe 相關資源，然後再次連結：

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

負載平衡器不應該有公用 IP

嘗試建立或連結 AKS 叢集時，您可能會收到一則訊息，指出因為「負載平衡器不應該有公用 IP」，所以要求遭到拒絕。當系統管理員已套用原則以防止使用具有公用 IP 位址的 AKS 叢集時，就會傳回此訊息。

若要解決此問題，請使用 load_balancer_type 和 load_balancer_subnet 參數建立/連結叢集。如需詳細資訊，請參閱內部負載平衡器 (私人 IP)。

共用方式為

使用 v1 建立並連結 Azure Kubernetes Service 叢集

必要條件

限制

Azure Kubernetes Service 版本

可用和預設版本

建立新的 AKS 叢集

連結現有的 AKS 叢集

使用 TLS 終止建立或連結 AKS 叢集

建立或連結 AKS 叢集以使用 Internal Load Balancer 搭配私人 IP

中斷連結 AKS 叢集

疑難排解

更新叢集

Web 服務失敗

負載平衡器不應該有公用 IP

下一步

意見反應

其他資源

共用方式為

使用 v1 建立並連結 Azure Kubernetes Service 叢集

必要條件

限制

Azure Kubernetes Service 版本

可用和預設版本

建立新的 AKS 叢集

連結現有的 AKS 叢集

使用 TLS 終止建立或連結 AKS 叢集

建立或連結 AKS 叢集以使用 Internal Load Balancer 搭配私人 IP

中斷連結 AKS 叢集

疑難排解

更新叢集

Web 服務失敗

刪除 azureml-fe 相關資源

負載平衡器不應該有公用 IP

下一步

意見反應

其他資源