通过

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

如何在 Azure Kubernetes 服务 (AKS) 中使用服务连接器

  • 项目

Azure Kubernetes 服务 (AKS) 是服务连接器支持的计算服务之一。 本文旨在帮助你了解：

  • 创建服务连接时，会在群集上进行哪些操作。
  • 如何使用服务连接器创建的 kubernetes 资源。
  • 如何在 AKS 群集中对服务连接器进行故障排除并查看其日志。

先决条件

服务连接器会在群集上执行哪些操作

根据在创建服务连接时选择的不同目标服务和身份验证类型，服务连接器会在 AKS 群集上执行不同的操作。 下面列出了服务连接器可能执行的操作。

添加服务连接器 kubernetes 扩展

第一次创建服务连接时，会将名为 sc-extension 的 kubernetes 扩展添加到群集。 稍后，每当有服务连接请求传入服务连接器时，该扩展都将帮助在用户的群集中创建 kubernetes 资源。 你可以在 Azure 门户打开自己的 AKS 群集，然后在“扩展 + 应用程序”菜单中找到该扩展。

Azure 门户的屏幕截图，用于查看 AKS 扩展。

该扩展也是存储群集连接元数据的位置。 卸载该扩展会使群集中的所有连接都不可用。 扩展运算符托管在群集命名空间 sc-system 中。

创建 kubernetes 资源

服务连接器会为用户在创建服务连接时指定的命名空间创建一些 kubernetes 资源。 这些 kubernetes 资源将存储连接信息，用户的工作负载定义或应用程序代码需要使用这些信息才能与目标服务通信。 根据不同的身份验证类型，会创建不同的 kubernetes 资源。 对于 Connection String 和 Service Principal 身份验证类型，将创建 kubernetes 机密。 对于 Workload Identity 身份验证类型，除了 kubernetes 机密之外，还会创建 kubernetes 服务帐户。

你可以在 Azure 门户中打开自己的 kubernetes 资源，然后在“服务连接器”菜单中找到由服务连接器为每个服务连接创建的 kubernetes 资源。

Azure 门户的屏幕截图，用于查看服务连接器创建的 kubernetes 资源。

删除服务连接不会删除关联的 Kubernetes 资源。 如有必要，请手动移除资源（例如使用 kubectl delete 命令）。

启用 azureKeyvaultSecretsProvider 加载项

如果目标服务是 Azure 密钥保管库，并且在创建服务连接时启用了机密存储 CSI 驱动程序，则服务连接器将为群集启用 azureKeyvaultSecretsProvider 加载项。

Azure 门户的屏幕截图，显示在创建连接时为密钥保管库启用了 CSI 驱动程序。

按照使用 CSI 驱动程序连接到 Azure 密钥保管库教程，使用机密存储 CSI 驱动程序设置与 Azure 密钥保管库的连接。

启用工作负载标识和 OpenID Connect (OIDC) 颁发者

如果在创建服务连接时的身份验证类型为 Workload Identity，则服务连接器将为群集启用工作负载标识和 OIDC 颁发者。

Azure 门户的屏幕截图，其中显示了使用工作负载标识创建连接。

当身份验证类型为 Workload Identity 时，需要具有用户分配的托管标识才能创建联合标识凭据。 请通过什么是工作负载标识一文了解详情，或按照教程来使用工作负载标识设置与 Azure 存储的连接。

如何使用服务连接器创建的 kubernetes 资源

当目标服务类型和身份验证类型不同时，会创建不同的 kubernetes 资源。 以下部分演示了如何在群集工作负载定义和应用程序代码中使用服务连接器创建的 kubernetes 资源。

Kubernetes 机密

当身份验证类型为 Connection String 或 Service Principal 时，将创建 kubernetes 机密。 群集工作负载定义可以直接引用该机密。 下面是一个示例。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
spec:
  template:
    spec:
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

然后，应用程序代码可以使用来自环境变量的机密中的连接字符串。 你可以查看示例代码，详细了解环境变量的名称以及如何在应用程序代码中使用它们来向不同的目标服务进行身份验证。

kubernetes 服务帐户

当身份验证类型为 Workload Identity 时，会同时创建 kubernetes 服务帐户和机密。 群集工作负载定义可以引用该服务帐户和机密，以通过工作负载标识进行身份验证。 以下代码片段提供了一个示例。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
  labels:
    azure.workload.identity/use: "true"
spec:
  template:
    spec:
      serviceAccountName: <ServiceAccountCreatedByServiceConnector>
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

你可以查看相应教程，了解如何使用工作负载标识连接到 Azure 存储。

如何进行故障排除并查看日志

如果在创建服务连接时发生错误且无法通过重试得到缓解，则以下方法可帮助收集更多信息来进行故障排除。

检查服务连接器 kubernetes 扩展

服务连接器 kubernetes 扩展是基于已启用 Azure Arc 的 Kubernetes 群集扩展构建的。 请使用以下命令调查扩展安装或更新期间是否存在任何错误。

  1. 安装 k8s-extension Azure CLI 扩展。
az extension add --name k8s-extension
  1. 获取服务连接器扩展的状态。 检查命令输出中的 statuses 属性，以查看是否存在任何错误。
az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

检查 kubernetes 群集日志

如果在扩展安装过程中出错，但 statuses 属性中的错误消息未能提供足够的信息来说明所发生的情况，则可以使用以下步骤进一步检查 kubernetes 日志。

  1. 连接到 AKS 群集。

    az aks get-credentials \
    --resource-group MyClusterResourceGroup \
    --name MyCluster

  2. 服务连接器扩展通过 helm 图表安装在命名空间 sc-system 中，请通过以下命令检查该命名空间和 helm 发布情况。

    • 检查命名空间是否存在。
    kubectl get ns
    • 检查 helm 发布状态。
    helm list -n sc-system

  3. 在扩展安装或更新期间，名为 sc-job 的 kubernetes 作业会为服务连接创建 kubernetes 资源。 该作业执行失败通常会导致扩展失败。 请运行以下命令来检查作业状态。 如果 sc-job 在 sc-system 命名空间中不存在，则应已成功执行。 此作业设计为在成功执行后自动删除。

    • 检查作业是否存在。
    kubectl get job -n sc-system
    • 获取作业状态。
    kubectl describe job/sc-job -n sc-system
    • 查看作业日志。
    kubectl logs job/sc-job -n sc-system

常见错误和缓解措施

Conflict

错误消息：Operation returned an invalid status code: Conflict。

原因：此错误通常在 AKS（Azure Kubernetes 服务）群集处于更新状态的情况下尝试创建服务连接时发生。 服务连接更新与正在进行的更新相冲突。 没有为 Microsoft.KubernetesConfiguration 资源提供程序注册你的订阅时，也可能发生这种情况。

缓解：

  • 运行以下命令，确保为 Microsoft.KubernetesConfiguration 资源提供程序注册你的订阅。

    az provider register -n Microsoft.KubernetesConfiguration

  • 确保你的群集处于“成功”状态，然后重试创建。

超时

错误消息：

  • Long running operation failed with status 'Failed'. Unable to get a response from the Agent in time。
  • Timed out waiting for the resource to come to a ready/completed state

原因：当用于创建或更新服务连接器群集扩展的 Kubernetes 作业由于资源限制或其他问题而无法计划时，通常会发生此错误。

缓解措施：参阅检查 Kubernetes 群集日志以识别详细原因并解决问题。 一个常见问题是因资源争用而没有可用的节点。 在这种情况下，请考虑添加更多节点或为节点启用自动缩放。

未经授权的资源访问

错误消息：You do not have permission to perform ... If access was recently granted, please refresh your credentials。

原因：服务连接器需有权操作你要连接到的 Azure 资源，这样才能代表你执行连接操作。 此错误表示对某些 Azure 资源缺少所需的权限。

缓解措施：检查对错误消息中指定的 Azure 资源的权限。 获取所需的权限并重试创建。

缺少订阅注册

错误消息：The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration'

原因：服务连接器要求为 Microsoft.KubernetesConfiguration（已启用 Azure Arc 的 Kubernetes 群集扩展的资源提供程序）注册该订阅。

迁移：通过运行以下命令注册 Microsoft.KubernetesConfiguration 资源提供程序。 有关资源提供程序注册错误的详细信息，请参阅此教程。

az provider register -n Microsoft.KubernetesConfiguration

其他问题

如果上述缓解措施无法解决问题，请尝试重置服务连接器群集扩展，方法是将其删除，然后重试创建。 此方法预期可以解决与服务连接器群集扩展相关的大多数问题。

使用以下 CLI 命令重置扩展：

az extension add --name k8s-extension

az k8s-extension delete \
    --resource-group <MyClusterResourceGroup> \
    --cluster-name <MyCluster> \
    --cluster-type managedClusters \
    --name sc-extension

后续步骤

了解如何集成不同的目标服务并了解其配置设置和身份验证方法。

了解如何集成存储 blob