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

“自定义位置”功能提供了一种方法来将已启用 Azure Arc 的 Kubernetes 群集配置为用于部署 Azure 产品/服务实例的目标位置。 可以部署在自定义位置上的 Azure 产品/服务的示例包括应用程序实例,例如 Functions 和逻辑应用。

自定义位置与已启用 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
      

    如果已安装 connectedk8sk8s-extensioncustomlocation 扩展,则可以通过使用以下命令将其更新到最新版本

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

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

重要

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

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

必须在创建自定义位置之前启用自定义位置功能,因为启用提供了在 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 服务群集扩展:

  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 群集上启用自定义位置功能。 启用该功能后,可以按照步骤创建自定义位置。

后续步骤