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

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

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

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

先决条件

• 将 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 文件。

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

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

若要以 Microsoft Entra 用户身份启用自定义位置功能，请遵循以下步骤：

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

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

要使用服务主体启用自定义位置功能，请遵循以下步骤：

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

1. 以 Microsoft Entra 用户身份登录到 Azure CLI。

2. 运行以下命令获取自定义位置 oid（对象 ID），其中 --id 指的是自定义位置服务应用本身，它是预定义的，且设置为 bc313c14-388c-4e7d-a58e-70017303ee3b：

   重要说明！ 完整复制并运行该命令，如下所示。 请勿将传递给 --id 参数的值替换为其他值。

   az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv
   

3. 使用服务主体登录到 Azure CLI。 运行以下命令，使用上一步中针对 oid 参数的 --custom-locations-oid（对象 ID）值在群集上启用自定义位置功能：

   az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <cl-oid> --features cluster-connect custom-locations
   

创建自定义位置

1. 在群集上部署要安装的 Azure 服务实例的 Azure 服务群集扩展：

   • 已启用 Azure Arc 的数据服务

     注意

     已启用 Azure Arc 的数据服务群集扩展支持不使用身份验证的出站代理，以及使用基本身份验证的出站代理。 目前不支持需要受信任证书的出站代理。

   • Azure Arc 上的 Azure 容器应用

   • Kubernetes 上的事件网格

2. 获取已启用 Azure Arc 的 Kubernetes 群集的 Azure 资源管理器标识符，此标识符在后面的步骤中称为 connectedClusterId：

   az connectedk8s show -n <clusterName> -g <resourceGroupName>  --query id -o tsv
   

3. 获取你部署到已启用 Azure Arc 的 Kubernetes 群集上的群集扩展的 Azure 资源管理器标识符，此标识符在后面的步骤中称为 extensionId：

   az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName>  --query id -o tsv
   

4. 通过引用已启用 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。

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

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

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

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

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> 

故障排除

Azure CLI v2.70.0 上的登录凭据错误

可能会遇到包含： TypeError: get_login_credentials() got an unexpected keyword argument 'resource'的错误。 Azure CLI v2.70.0 发布了一项重大变更，导致出现此错误。 自定义分配 Az CLI 扩展 v0.1.4 中提供了修补程序，以便与 Azure CLI v2.70.0 及更高版本兼容。 如果使用 v0.1.4 以下的 customlocation Az CLI 扩展，则需要将 Azure CLI 降级到版本 2.69.0。 如果使用 Azure CLI 安装程序，可以卸载当前版本并从 Azure CLI installation page 安装 Azure CLI v2.69.0。 如果使用 pip 安装程序，可以运行以下命令来降级：pip install azure-cli==2.69.0。

未知代理错误

如果自定义位置创建失败并出现错误 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.

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

后续步骤

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