使用 v1 创建并附加 Azure Kubernetes 服务群集
重要
本文介绍如何使用 CLI 和 SDK v1 创建或附加 Azure Kubernetes 服务群集，此功能现在被视为旧功能。 若要使用 v2 的建议方法附加 Azure Kubernetes 服务群集，请参阅 v2 中的 Kubernetes 计算目标简介。
Azure 机器学习可以将经过训练的机器学习模型部署到 Azure Kubernetes 服务。 但是，必须首先从 Azure 机器学习工作区创建 Azure Kubernetes 服务 (AKS) 群集，或者附加现有 AKS 群集。 本文提供了有关创建和附加群集的信息。
先决条件
Azure 机器学习工作区。 有关详细信息，请参阅创建 Azure 机器学习工作区。
机器学习服务的 Azure CLI 扩展 (v1)、Azure 机器学习 Python SDK 或 Azure 机器学习 Visual Studio Code 扩展。
重要
本文中的一些 Azure CLI 命令使用适用于 Azure 机器学习的
azure-cli-ml或 v1 扩展。 对 v1 扩展的支持将于 2025 年 9 月 30 日结束。 在该日期之前，你将能够安装和使用 v1 扩展。建议在 2025 年 9 月 30 日之前转换为
ml或 v2 扩展。 有关 v2 扩展的详细信息，请参阅 Azure ML CLI 扩展和 Python SDK v2。如果计划使用 Azure 虚拟网络来保护 Azure 机器学习工作区与 AKS 群集之间的通信，则工作区及其关联的资源（存储、密钥保管库、Azure 容器注册表）必须在与 AKS 群集的同一 VNET 中具有专用终结点或服务终结点。 请按照教程创建安全工作区，将这些专用终结点或服务终结点添加到 VNET。
限制
一个 AKS 只能创建或附加为 Azure 机器学习工作区中的单个计算目标。 不支持多次附加一个 AKS。
如果群集中需要部署的是标准负载均衡器 (SLB)，而不是基本负载均衡器 (BLB)，请在 AKS 门户/CLI/SDK 中创建群集，然后将该群集附加到 Azure 机器学习工作区。
如果你的 Azure Policy 限制创建公共 IP 地址，则无法创建 AKS 群集。 AKS 需要一个公共 IP 用于出口流量。 出口流量一文还指导如何通过公共 IP（几个完全限定的域名的 IP 除外）锁定来自群集的出口流量。 启用公共 IP 有两种方法：
- 群集可以使用在默认情况下与 BLB 或 SLB 一起创建的公共 IP，或者
- 可以在没有公共 IP 的情况下创建群集，然后为公共 IP 配置一个带有用户定义路由的防火墙。 有关详细信息，请参阅使用用户定义的路由自定义群集出口。
Azure 机器学习控制平面不会与此公共 IP 通信。 它与 AKS 控制平面通信以便进行部署。
若要附加 AKS 群集，必须在包含群集的 Azure 资源组上为执行该操作的服务主体/用户分配“所有者或参与者”Azure 基于角色的访问控制 (Azure RBAC) 角色。 还必须在群集上为服务主体/用户分配 Azure Kubernetes 服务群集管理员角色。
如果附加 AKS 群集（已启用授权 IP 范围来访问 API 服务器），请为该 AKS 群集启用 Azure 机器学习控制平面 IP 范围。 Azure 机器学习控制平面是跨配对区域部署的，并且会在 AKS 群集上部署推理 Pod。 如果无法访问 API 服务器，则无法部署推理 Pod。 在 AKS 群集中启用 IP 范围时，请对两个配对区域都使用 IP 范围。
授权 IP 范围仅适用于标准负载均衡器。
如果要使用专用 AKS 群集（使用 Azure 专用链接），则必须先创建群集，然后再将其附加到工作区。 有关详细信息，请参阅创建专用 Azure Kubernetes 服务群集。
Azure 机器学习不支持使用具有专用 AKS 群集的公共完全限定的域名 (FQDN)。
AKS 群集的计算名称在 Azure 机器学习工作区中必须是唯一的。 它可以包含字母、数字和短划线。 它必须以字母开头，以字母或数字结尾，长度为 3 到 24 个字符。
如果要将模型部署到 GPU 节点或 FPGA 节点（或任何特定 SKU），则必须使用该特定 SKU 创建群集。 不支持在现有群集中创建辅助节点池以及在辅助节点池中部署模型。
创建或附加群集时，可以选择为开发/测试还是生产创建群集。 如果要创建 AKS 群集以用于开发、验证和测试而非生产，请将“群集用途”设置为“开发/测试” 。 如果未指定群集用途，则会创建生产群集。
重要
开发/测试群集不适用于生产级别的流量，并且可能会增加推理时间。 开发/测试群集也不保证容错能力。
创建或附加群集时，如果群集将用于生产，则它必须至少包含 3 个节点。 对于“开发测试”群集，它必须至少包含 1 个节点。
Azure 机器学习 SDK 不支持缩放 AKS 群集。 要缩放群集中的节点，请在 Azure 机器学习工作室中使用 AKS 群集的 UI。 只能更改节点计数，不能更改群集的 VM 大小。 有关缩放 AKS 群集中节点的详细信息，请参阅以下文章：
不要使用 YAML 配置直接更新群集。 虽然 Azure Kubernetes 服务支持通过 YAML 配置进行更新，但 Azure 机器学习部署将覆盖更改。 唯一不会覆盖的两个 YAML 字段为“请求限制”和“CPU 和内存”。
使用 Azure 机器学习工作室 UI、SDK 或 CLI 扩展来创建 AKS 群集的过程并不是幂等的。 再次尝试创建资源会导致错误，因为已存在具有相同名称的群集。
- 使用 Azure 资源管理器模板和 Microsoft.MachineLearningServices/workspaces/computes 资源来创建 AKS 群集也不是幂等的。 如果再次尝试使用该模板来更新已有的资源，会收到相同的错误。
Azure Kubernetes 服务版本
Azure Kubernetes 服务允许使用各种 Kubernetes 版本创建群集。 有关可用版本的详细信息，请参阅 Azure Kubernetes 服务支持的 Kubernetes 版本。
使用以下方法之一创建 Azure Kubernetes 服务群集时，无法选择创建的群集的版本：
- Azure 机器学习工作室，或 Azure 门户的“Azure 机器学习”部分。
- 适用于 Azure CLI 的机器学习扩展。
- Azure 机器学习 SDK。
这些创建 AKS 群集的方法使用默认的群集版本。 当有新的 Kubernetes 版本可用时，默认版本会随时间的推移而改变。
附加现有 AKS 群集时，我们为当前受支持的所有 AKS 版本提供支持。
重要
Azure Kubernetes 服务对 <=1.16 的版本使用 Blobfuse FlexVolume 驱动程序，对 >=1.17 的版本使用 Blob CSI 驱动程序。 因此，请务必在群集升级后重新部署或更新 Web 服务，以便为群集版本部署正确的 blobfuse 方法。
注意
可能会出现旧群集不再受支持的极端情况。 在这种情况下，附加操作会返回一个错误，并会列出当前受支持的版本。
你可以附加预览版。 提供的预览版功能不附带服务级别协议，我们不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 对使用预览版的支持可能会受到限制。 有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。
可用版本和默认版本
若要查找可用的和默认的 AKS 版本，请使用 Azure CLI 命令 az aks get-versions。 例如，以下命令返回中国北部区域中可用的版本：
az aks get-versions -l chinanorth -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 机器学习创建群集时使用的默认版本，可以使用 --query 参数选择默认版本：
az aks get-versions -l chinanorth --query "orchestrators[?default == `true`].orchestratorVersion" -o table
此命令的输出类似于以下文本：
Result
--------
1.16.13
若要以编程方式检查可用版本，请使用容器服务客户端 - 列出业务流程协调程序 REST API。 若要查找可用版本，请查看 orchestratorType 为 Kubernetes 的条目。 关联的 orchestrationVersion 条目包含可附加到你的工作区的可用版本。
若要查找通过 Azure 机器学习创建群集时使用的默认版本，请找到其中的 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 群集：
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)
有关此示例中使用的类、方法和参数的详细信息，请参阅以下参考文档：
附加现有的 AKS 群集
时间估计：大约 5 分钟。
如果 Azure 订阅中已有 AKS 群集，则可以将其与工作区配合使用。
提示
现有的 AKS 群集除了位于 Azure 机器学习工作区，还可位于 Azure 区域中。
警告
不要在同一个 AKS 群集中创建多个同步附件。 例如，使用两个不同的名称将一个 AKS 群集附加到某个工作区，或将一个 AKS 群集附加到不同的工作区。 每个新附件会破坏以前的现有附件，并导致不可预知的错误。
如果要重新附加 AKS 群集（例如，更改 TLS 或其他群集配置设置），则必须先使用 AksCompute.detach() 删除现有附件。
有关如何使用 Azure CLI 或门户创建 AKS 群集的详细信息，请参阅以下文章：
以下示例演示如何将现有 AKS 群集附加到工作区：
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)
有关此示例中使用的类、方法和参数的详细信息，请参阅以下参考文档：
使用“TLS 终止”创建或附加 AKS 群集
创建或附加 AKS 群集时，可以使用 AksCompute.provisioning_configuration() 和 AksCompute.attach_configuration() 配置对象来启用 TLS 终止 。 这两种方法都返回一个具有 enable_ssl 方法的配置对象，你可以使用 enable_ssl 方法启用 TLS。
以下示例演示了如何在后台使用 Microsoft 证书通过自动 TLS 证书生成和配置来启用 TLS 终止。
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>.chinacloudapp.cn"
# 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>.chinacloudapp.cn"
# where "######" is a random series of characters
attach_config.enable_ssl(leaf_domain_label = "contoso")
以下示例演示如何使用自定义证书和自定义域名来启用 TLS 终止。 使用自定义域和证书时，需要更新 DNS 记录，使其指向评分终结点的 IP 地址，请参阅更新 DNS
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 机器学习确保 Web 服务安全
创建或附加 AKS 群集以使用具有专用 IP 的内部负载均衡器
创建或附加 AKS 群集时，可以将群集配置为使用内部负载均衡器。 使用内部负载均衡器时，部署到 AKS 的评分终结点会在虚拟网络中使用专用 IP。 以下代码片段演示了如何为 AKS 群集配置内部负载均衡器。
若要创建使用内部负载均衡器的 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)
重要
如果为 AKS 群集配置了内部负载均衡器，则不支持使用 Azure 提供的证书，你必须使用用于启用 TLS 的自定义证书。
注意
有关如确保推理环境安全的详细信息，请参阅确保 Azure 机器学习推理环境安全
拆离 AKS 群集
若要从工作区拆离群集，请使用以下方法之一：
警告
使用 Azure 机器学习工作室、SDK 或适用于机器学习的 Azure CLI 扩展来拆离 AKS 群集不会删除 AKS 群集。 若要删除群集，请参阅将 Azure CLI 与 AKS 配合使用。
aks_target.detach()
疑难解答
更新群集
必须手动应用对 Azure Kubernetes 服务群集中安装的 Azure 机器学习组件的更新。
可以通过从 Azure 机器学习工作区分离群集，然后将群集重新附加到工作区，来应用这些更新。
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 证书和私钥。
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 机器学习生成的证书，则可以在分离群集之前，使用 kubectl 连接到群集并检索机密 azuremlfessl 来检索文件。
kubectl get secret/azuremlfessl -o yaml
注意
Kubernetes 存储的机密采用 Base64 编码格式。 在将机密提供给 attach_config.enable_ssl 之前，需要对机密的 cert.pem 和 key.pem 组成部分进行 Base64 解码。
Web 服务失败
对于 AKS 中的许多 Web 服务失败，可以使用 kubectl 连接到群集进行调试。 可以通过运行以下内容来获取 AKS 群集的 kubeconfig.json
az aks get-credentials -g <rg> -n <aks cluster name>
删除 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
负载均衡器不应具有公共 IP
尝试创建或附加 AKS 群集时，可能会收到一条消息，指出请求已被拒绝，因为“负载均衡器不应具有公共 IP”。 当管理员应用了阻止使用具有公共 IP 地址的 AKS 群集的策略时，将返回此消息。
若要解决此问题，请使用 load_balancer_type 和 load_balancer_subnet 参数创建/附加群集。 有关详细信息，请参阅内部负载均衡器（专用 IP）。