你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在已启用 Azure Arc 的 Kubernetes 上创建和管理自定义位置

2025-10-17

通过“自定义位置”功能，可以将已启用 Azure Arc 的 Kubernetes 群集配置为 Azure 产品/服务实例的目标部署位置。可在自定义位置之上部署的 Azure 产品/服务的示例包括数据库，例如 Azure Arc 启用的 SQL 托管实例或应用程序实例，例如容器应用、逻辑应用、事件网格、逻辑应用和 API 管理。

自定义位置与已启用 Azure Arc 的 Kubernetes 群集中的命名空间有一对一的映射。将 Azure 资源与 Azure 基于角色的访问控制 (Azure RBAC) 结合使用的自定义位置可用于向应用程序开发人员或数据库管理员授予细化权限，让他们能够在多租户环境中已启用 Arc 的 Kubernetes 群集顶层部署资源，例如数据库或应用程序实例。

本文将介绍如何在已启用 Arc 的 Kubernetes 群集上启用自定义位置，以及如何创建自定义位置。

Prerequisites

将 Azure CLI 安装或升级到最新版本。

安装以下 Azure CLI 扩展的最新版本：

connectedk8s
k8s-extension

customlocation

az extension add --name connectedk8s
az extension add --name k8s-extension
az extension add --name customlocation

如果已安装 connectedk8s、 k8s-extension扩展和 customlocation 扩展，请使用以下命令更新到 最新版本 ：

az extension update --name connectedk8s
az extension update --name k8s-extension
az extension update --name customlocation

验证 Microsoft.ExtendedLocation 的提供程序注册是否已完成。
1. 输入以下命令：
```
az provider register --namespace Microsoft.ExtendedLocation
```
2. 监视注册过程。注册可能最多需要 10 分钟。
```
az provider show -n Microsoft.ExtendedLocation -o table
```
  注册后，状态 RegistrationState 具有值 Registered。
验证是否具有已启用 Azure Arc 的 Kubernetes 连接群集，并将代理升级到最新版本。确认运行本文中所述命令的计算机具有一个指向此群集的kubeconfig文件。

在自己的群集上启用自定义位置

重要说明

自定义位置功能依赖于群集连接功能。必须在群集中启用这两项功能才能使自定义位置正常工作。

启用自定义位置需要自定义位置对象 ID (OID)。如果你的用户帐户具有所需权限，在功能启用期间将自动检索 OID。如果没有有效的用户帐户，则使用手动传递的 OID，但无法验证 OID。如果 OID 无效，那么自定义位置可能无法正确启用。

必须在创建自定义位置之前启用自定义位置功能，因为启用提供了在 Kubernetes 群集上创建自定义位置命名空间所需的权限。

以Microsoft Entra 用户身份启用自定义位置

以 Microsoft Entra 用户身份登录到 Azure CLI 并运行以下命令：

az connectedk8s enable-features -n <clusterName> -g <resourceGroupName> --features cluster-connect custom-locations

使用服务主体启用自定义位置

按照以下步骤手动检索自定义位置 OID。

重要说明

复制并运行步骤 2 中的命令，如下所示。不要将传递给 --id 参数的值替换为其他值。

以 Microsoft Entra 用户身份登录到 Azure CLI。
运行以下命令获取自定义位置 oid（对象 ID），其中 --id 指的是自定义位置服务应用本身，它是预定义的，且设置为 bc313c14-388c-4e7d-a58e-70017303ee3b：
```
az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv
```
使用服务主体登录到 Azure CLI。运行以下命令，使用上一步中针对 --custom-locations-oid 参数的 oid（对象 ID）值在群集上启用自定义位置功能：
```
az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <cl-oid> --features cluster-connect custom-locations
```

创建自定义位置

在群集上部署要安装的 Azure 服务实例的 Azure 服务群集扩展：
- 已启用 Azure Arc 的数据服务
  
  注意
  
  已启用 Azure Arc 的数据服务群集扩展支持不使用身份验证的出站代理，以及使用基本身份验证的出站代理。目前不支持需要受信任证书的出站代理。
- Azure Arc 上的 Azure 容器应用
- Kubernetes 上的事件网格
获取已启用 Azure Arc 的 Kubernetes 群集的 Azure 资源管理器标识符，此标识符在后面的步骤中称为 connectedClusterId：
```
az connectedk8s show -n <clusterName> -g <resourceGroupName>  --query id -o tsv
```
获取部署到已启用 Azure Arc 的 Kubernetes 群集的群集扩展的 Azure 资源管理器标识符，此标识符在后面的步骤中称为 extensionId：
```
az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName>  --query id -o tsv
```

通过引用已启用 Azure Arc 的 Kubernetes 群集和扩展来创建自定义位置：

az customlocation create -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionId>

所需参数：

参数名称	说明
`--name, --n`	自定义位置的名称。
`--resource-group, --g`	自定义位置的资源组。
`--namespace`	群集中绑定到所创建的自定义位置的命名空间。
`--host-resource-id`	已启用 Azure Arc 的 Kubernetes 群集（连接的群集）的 Azure 资源管理器标识符。
`--cluster-extension-ids`	已连接群集上安装的群集扩展实例的 Azure 资源管理器标识符。对于多个扩展，请提供群集扩展 ID 的空格分隔列表

可选参数：

参数名称	说明
`--location, --l`	Azure 资源管理器资源在 Azure 中的自定义位置。如果未指定，则使用连接的群集的位置。
`--tags`	空格分隔的标记列表，格式为 `key[=value]`。使用 '' 清除现有标记。
`--kubeconfig`	群集的管理员 `kubeconfig`。

确认自定义位置已成功启用，方法是运行以下命令并检查 ProvisioningState 是否为 Succeeded：

az customlocation show -n <customLocationName> -g <resourceGroupName>

检查自定义位置的使用情况

若要确定其他 Azure 资源是否主动使用自定义位置，可以使用 Azure CLI 列出为其启用的资源类型。

az customlocation list-enabled-resource-types -n <customLocationName> -g <resourceGroupName>

此命令返回配置为使用指定自定义位置的 Azure 资源类型的列表。如果列表不为空，则表示这些资源类型当前正在使用自定义位置。

示例输出：

[
  {
    "resourceType": "Microsoft.App/containerApps"
  },
  {
    "resourceType": "Microsoft.Data/sqlManagedInstances"
  }
]

显示自定义位置的详细信息

若要显示自定义位置的详细信息，请使用以下命令：

az customlocation show -n <customLocationName> -g <resourceGroupName>

列出自定义位置

若要列出资源组中的所有自定义位置，请使用以下命令：

az customlocation list -g <resourceGroupName>

更新自定义位置

使用 update 命令为 --tags 添加新值，或者将新的 --cluster-extension-ids 关联到自定义位置，同时保留标记及关联群集扩展的现有值。

az customlocation update -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>

修补自定义位置

使用 patch 命令替换 --cluster-extension-ids 或 --tags 的现有值。以前的值不会保留。

az customlocation patch -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>

删除自定义位置

若要删除自定义位置，请使用以下命令：

az customlocation delete -n <customLocationName> -g <resourceGroupName>

疑难解答

可能会遇到包含： TypeError: get_login_credentials() got an unexpected keyword argument 'resource'的错误。 Azure CLI v2.70.0 发布了触发此错误的重大更改。 v0.1.4 中 az customlocation 提供了修补程序，以便与 Azure CLI v2.70.0 及更高版本兼容。

若要使用较低版本的版本 az customlocation，还必须使用 Azure CLI 2.69.0 或更高版本。如果使用 Azure CLI 安装程序，可以卸载当前版本并从 Azure CLI installation page 安装 Azure CLI v2.69.0。如果使用 pip 安装程序，可以运行以下命令来降级：pip install azure-cli==2.69.0。但是，我们通常建议同时使用 az customlocation 和 Azure CLI 的最新版本。

未知代理错误

如果自定义位置创建失败并出现错误 Unknown proxy error occurred，请修改网络策略，以在 azure-arc 命名空间中允许 Pod 到 Pod 内部通信。确保也将 azure-arc 命名空间添加为你配置的策略的无代理排除列表的一部分。

服务主体警告

如果在使用服务主体登录到 Azure CLI 时尝试启用自定义位置，可能会看到以下警告：

Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation.

发生此警告是因为服务主体缺少检索 Azure Arc 服务使用的自定义位置的 oid（对象 ID）所需的权限。按照提供的说明使用服务主体启用自定义位置功能。

资源提供方没有必要权限

如果在 Kubernetes 群集上启用自定义位置功能之前尝试创建自定义位置，可能会收到以下错误消息：

Deployment failed. Correlation ID: ... "Microsoft.ExtendedLocation" resource provider does not have the required permissions to create a namespace on the cluster. Refer to https://aka.ms/ArcK8sCustomLocationsDocsEnableFeature to provide the required permissions to the resource provider.

首先，在群集上启用自定义位置功能。启用该功能后，可以按照步骤创建自定义位置。

Next steps

使用群集连接功能安全地连接到群集。
继续学习 Azure Arc 上的 Azure 容器应用，获取有关安装扩展、创建自定义位置以及创建 Azure 容器应用连接环境的端到端说明。
详细了解当前可用的 Azure Arc 启用的 Kubernetes 扩展。

反馈

此页面是否有帮助？