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

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

2025-06-27

Azure Kubernetes 服务 (AKS) 是服务连接器支持的计算服务之一。

本文介绍：

AKS 服务连接器和其他计算服务之间的差异。
在创建服务连接期间在群集上执行的操作。
在创建服务连接期间对目标服务执行的操作。
使用服务连接器创建的 Kubernetes 资源。
对 AKS 群集中的服务连接器日志进行故障排除和查看。

先决条件

本指南假定你已了解服务连接器基本概念。

AKS 服务连接器和其他计算服务之间的差异

适用于 AKS 的服务连接器与服务连接器支持的其他计算服务的工作方式不同。下面概述了每个 API 操作的 AKS 特定选项和行为。

创建

下面列出了特定于 AKS 的创建选项。请参阅 Azure 门户或 Azure CLI 快速入门，了解如何在 AKS 中创建新连接。

AKS 的服务连接器需要 Kubernetes namespace 参数来指定在何处创建 Kubernetes 资源。默认情况下，它使用 default 命名空间。
AKS 服务连接器支持 Workload Identity 作为安全凭据身份验证选项，而其他计算服务提供 System Managed Identity 和 User Managed Identity 选项。
将 Azure Key Vault 用作启用了机密存储 CSI 驱动程序的目标服务时，服务连接器使用 AKS azure-keyvault-secrets-provider 加载项中的用户分配的托管标识进行身份验证，而无需用户指定身份验证类型。
AKS 的服务连接器仅支持 Firewall Rules 网络选项，而其他计算服务也可能支持 Private Link 和 Virtual Network 选项。

列出配置

AKS 的服务连接器仅在列表配置视图中显示非凭据配置。如果需要，用户应手动检查关联的 Kubernetes 资源中的凭据。

使用 Azure CLI 命令 az aks connection list-configuration，凭据配置的值是空字符串。在 Azure 门户中，凭据配置的值处于隐藏状态，如下所示。

AKS 连接列表配置的屏幕截图。

验证

适用于 AKS 的服务连接器不会验证用户群集中所做的配置值更改，无论是凭据还是非凭据配置。但是，服务连接器执行以下验证，就像对其他计算服务所做的那样：

验证目标服务是否存在
检查 IP 防火墙规则以访问目标服务
确保工作负载标识的角色分配以访问目标服务

Azure CLI 命令 az aks connection validate 的输出始终为success。这同样适用于 Azure 门户，如下所示。

AKS 连接验证的屏幕截图。

服务连接器在 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 Key Vault，并且启用了机密存储 CSI 驱动程序，则服务连接器将为群集启用 azureKeyvaultSecretsProvider 加载项。

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

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

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

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

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

如果身份验证类型为 Workload Identity，则需要用户分配的托管标识来创建联合标识凭据。详细了解工作负荷标识，或参阅以下教程，了解如何使用工作负荷标识设置与 Azure 存储的连接。

服务连接器在目标服务上执行的操作

AKS 的服务连接器对目标服务执行与其他计算服务相同的操作。然而，操作会因目标服务类型和身份验证方法的不同而有所变化。下面列出了一些可能的操作。

获取连接配置

服务连接器从目标服务检索所需的连接配置，并将其设置为用户群集中的 Kubernetes 机密。连接配置因目标服务类型和身份验证方法而异：

Connection String对于身份验证类型，配置通常包括服务机密或连接字符串。
Workload Identity对于身份验证类型，它通常包含服务终结点。
Service Principal对于身份验证类型，它包含服务主体的租户 ID、客户端 ID 和客户端密码。

有关特定目标服务的详细信息，请参阅相应的文档，例如 Azure AI 服务指南。

创建基于 IP 的防火墙规则

服务连接器从 AKS 群集检索出站公共 IP，并在目标服务上创建 IP 防火墙规则，以允许从群集进行网络访问。

创建 Microsoft Entra ID 角色分配

使用 Workload Identity 身份验证类型时，服务连接器会自动为标识创建角色分配。分配的角色因目标服务而异，以确保适当的访问权限。用户还可以根据需要自定义角色分配。有关详细信息，请参阅角色自定义。

使用服务连接器创建的 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 群集扩展构建的。使用以下命令检查扩展安装或更新过程中发生的任何错误。

安装 Azure CLI 扩展 k8s-extension。
```
az extension add --name k8s-extension
```

检索服务连接器扩展的状态。检查命令输出中的 statuses 属性以识别错误。

az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

查看 Kubernetes 群集日志

如果在扩展安装期间发生错误，并且属性中的 statuses 错误消息未提供足够的信息，则可以使用以下步骤检查 Kubernetes 日志来进一步调查。

连接到 AKS 群集。

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

服务连接器扩展使用 Helm 图表安装在 sc-system 命名空间中。使用以下命令检查命名空间和 Helm 版本。
- 检查命名空间是否存在。
```
kubectl get ns
```
- 检查 helm 发布状态。
```
helm list -n sc-system
```
在扩展安装或更新期间，名为 sc-job 的 Kubernetes 作业会为服务连接创建 Kubernetes 资源。作业执行失败通常会导致扩展失败。请运行以下命令来检查作业状态。如果 sc-system 命名空间中没有 sc-job，表示已成功执行。此作业设计为在成功执行后自动删除。
- 检查作业是否存在。
```
kubectl get job -n sc-system
```
- 获取作业状态。
```
kubectl describe job/sc-job -n sc-system
```
- 查看作业日志。
```
kubectl logs job/sc-job -n sc-system
```

常见错误和缓解措施

扩展创建错误

错误消息：

Unable to get a response from the agent in time。
Extension pods can't be scheduled if all the node pools in the cluster are "CriticalAddonsOnly" tainted

缓解：

请参阅扩展创建错误

Helm 错误

错误消息：

Unable to download the Helm chart from the repo URL

此错误是由群集与防火墙之间发生的连接问题以及出口阻止问题引起的。若要解决此问题，请参阅 Azure Kubernetes 服务 (AKS) 群集的出站网络和 FQDN 规则，并添加拉取 Service Connector Helm Chart 所需的 FQDN：scaksextension.azurecr.io

错误消息：

Timed out waiting for resource readiness
Helm chart rendering failed with given values
Resource already exists in your cluster
Operation is already in progress for Helm

缓解：

请参阅 Helm 错误

冲突

错误消息：

Operation returned an invalid status code: Conflict。

原因：

当 Azure Kubernetes 服务 (AKS) 群集处于更新状态时，尝试创建服务连接通常会引发此错误。服务连接更新与正在进行的更新相冲突。如果未向 Microsoft.KubernetesConfiguration 资源提供程序注册订阅，也会发生此错误。

缓解：

确保你的群集处于“成功”状态，然后重试创建。
运行以下命令，确保订阅已注册到 Microsoft.KubernetesConfiguration 资源提供程序。
```
az provider register -n Microsoft.KubernetesConfiguration
```

未经授权的资源访问

错误消息：

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

后续步骤

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

了解如何集成存储 blob

反馈

此页面是否有帮助？

通过

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

先决条件

AKS 服务连接器和其他计算服务之间的差异

创建

列出配置

验证

服务连接器在 AKS 群集上执行的操作

添加服务连接器 Kubernetes 扩展

创建 Kubernetes 资源

启用 azureKeyvaultSecretsProvider 加载项

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

服务连接器在目标服务上执行的操作

获取连接配置

创建基于 IP 的防火墙规则

创建 Microsoft Entra ID 角色分配

使用服务连接器创建的 Kubernetes 资源

Kubernetes 机密

Kubernetes 服务帐户

故障排除和查看日志

检查服务连接器 Kubernetes 扩展

查看 Kubernetes 群集日志

常见错误和缓解措施

扩展创建错误

Helm 错误

冲突

未经授权的资源访问

缺少订阅注册

后续步骤

反馈

其他资源

启用 `azureKeyvaultSecretsProvider` 加载项