通过

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

故障排除

机密存储扩展 (SSE) 创建一个包含两个容器的 Kubernetes 部署的 Pod：控制器负责管理集群中的机密存储、处理调度和配置，提供者则从 Azure Key Vault (AKV) 访问机密。 SSE 可以直接通过SecretSyncSecretProviderClass资源进行配置，也可以通过合并AKVSync资源进行配置，以便人类更容易理解。 除了配置参数之外，SSE 控制器还会更新 SecretSync 和 AKVSync 资源的同步操作状态，适时包括错误消息。

检查同步的状态

可以通过检查相关 SecretSync 或 AKVSync 对象的状态来调查 SSE 最常见的问题。 kubectl describe ...使用命令查看同步对象的状态。 除了总体配置之外，输出还包括机密创建时间戳、机密版本以及每个同步事件的详细状态消息。 此输出可用于诊断连接或配置错误，以及何时更改机密值。

如果使用简化的 （AKVSync） 样式配置，SSE 会自动生成等效 SecretSync 的资源。 没有必要直接检查这些资源；在检查生成SecretSync资源的AKVSync资源时，可以看到所有派生资源的状态。

基于 AKVSync 资源的简化配置：

kubectl describe akvsync <akvsync-name> -n <namespace>

基于 SecretSync 和 SecretProviderClass 的直接配置：

kubectl describe secretsync <secret-sync-name> -n <namespace>

SecretSync 状态原因

下表列出了常见状态原因、其含义以及解决错误的潜在故障排除步骤。 大多数诊断过程也适用于简化的配置，在本例中，将命令行示例中使用的 secretsync 替换为 akvsync。

SecretSync 状态原因 详细信息 进一步修复/调查的步骤
UpdateNoValueChangeSucceeded Kubernetes 中的机密与 AKV 版本完全同步更新，最后一次检查时为最新版本。 在最新版本检查期间无需进行任何更改。 n/a
UpdateValueChangeOrForceUpdateSucceeded 最新检查显示，Kubernetes 中的全部机密已成功更新，并包含必要的 AKV 版本。 n/a
PartialSync 无法更新机密中的某些项。 查看 status.conditions.message 对象的 SecretSync 字段以进一步调查。 此字段包含机密中每个项成功或失败的字符串化 json 摘要。
ProviderError 由于提供程序存在一些问题（与 Azure Key Vault 的连接），机密创建失败。 此失败可能是由于 Internet 连接、标识同步机密的权限不足、SecretProviderClass 配置错误或其他问题造成的。 首先按如下所示 PartialSync进行调查，接下来使用以下命令查看提供程序的日志：
kubectl get pods -n azure-secret-store
kubectl logs <secret-sync-controller-pod-name> -n azure-secret-store --container='provider-azure-installer'
InvalidClusterSecretLabelError
InvalidClusterSecretAnnotationError		 SSE 无法创建 Kubernetes 机密，因为存在具有相同名称的现有非 SSE 机密。 删除机密以允许 SSE 重新创建机密： kubectl delete secret <secret-name> -n <namespace>
若要强制 SSE 比配置的轮询间隔更快地重新创建机密，请删除 SecretSync 对象（kubectl delete secretsync <secret-name> -n <namespace>）并重新应用机密同步资源（kubectl apply -f <path_to_secret_sync> -n <namespace>）。
UserInputValidationFailed 机密更新失败，因为 SecretSync 资源配置不正确（例如机密类型无效）。 查看机密同步资源定义并更正任何错误。 然后，删除机密同步资源（kubectl delete -f <path_to_secret_sync>），并重新应用机密同步资源（kubectl apply -f <path_to_secret_sync>）。
ControllerSpcError 机密更新失败，因为 SSE 未能获取提供程序类或提供程序类配置错误。 查看提供程序类并更正任何错误。 然后，删除 SecretSync 对象 (kubectl delete secretsync <secret-name>)，删除提供程序类 (kubectl delete -f <path_to_provider>)，并重新应用提供程序类 (kubectl apply -f <path_to_provider>)。
ControllerInternalError
ValidatingAdmissionPolicyCheckFailed
ControllerSyncFailed		 由于 SSE 中的内部错误，机密更新失败。 有关详细信息，请查看 SSE 日志或事件：
kubectl logs -n secrets-store-sync-controller-system deployment/secrets-store-sync-controller-manager -f
UnknownError 在修补 Kubernetes 机密值期间，机密更新失败。 如果 SSE 以外的人修改了机密，或者 SSE 更新期间出现问题，则可能会发生此故障。 尝试删除机密和 SecretSync 对象，然后重新应用 SecretSync 该对象，让 SSE 重新创建机密：
kubectl delete secret <secret-name>
kubectl delete secretsync <secret-name>
kubectl apply -f <path_to_secret_sync>
如果此步骤没有帮助，请按照步骤检查日志，如下所示 ControllerInternalError。

网络访问问题

如果看到 ProviderError 状态原因，并有消息显示已超时或无法访问你的密钥保管库终结点 (<vault_name>.vault.azure.net)，表示可能有需要解决的网络访问问题。 可能的网络访问问题包括：

Azure Key Vault 防火墙配置

默认情况下，Azure Key Vault 具有宽松的防火墙配置，可以通过公共 Internet 访问，但最好限制对 Azure Key Vault 的网络访问。 仔细检查密钥保管库防火墙配置是否允许访问群集。 请参阅 Azure Key Vault 的网络安全性

Azure Arc 网关（预览版）

Azure Arc 网关（预览版）不提供与 Azure Key Vault 的网络连接。 必须独立允许网络访问 <vault_name>.vault.azure.net ，以便 SSE 可以同步机密。 请参阅相关的 Arc 网关 和 Azure Key Vault 文档。

如果使用 Azure Arc 专用链接：请确保 DNS 和网络允许 Arc 连接的群集访问 Key Vault 的专用终结点。 验证保管库名称的 DNS 解析是否返回专用 IP，以及是否已从群集正确路由专用链接 IP。 请参阅 诊断 Azure Key Vault 上的专用链接配置问题。

更新缓慢或缺失

机密存储扩展在检查 Azure Key Vault 以获取更新时，会等待一个设定的时间间隔。 在 AKV 中更新机密时，仅当间隔过期且 SSE 再次检查时，该机密才会下载到群集。 默认间隔为一小时（3,600 秒），通过配置设置进行设置 rotationPollIntervalInSeconds。 请参阅 配置参考。

若要强制 SSE 立即更新机密，请更新spec资源中的SecretSync字段的任何部分。 在一个对配置没有影响的 forceSynchronization 内，可以设置一个特殊字段 spec；如果 forceSynchronization 的值被修改，SSE 会立即更新秘密。 有关示例，请参阅 SecretSync 参考 。

Azure Key Vault 速率限制

在限制请求之前，Azure Key Vault 对它可以服务的事务速率有硬性限制。 请参阅 Azure Key Vault 服务限制。 对 AKV 的所有经过身份验证的请求都计入限制限制，即使它们不成功也是如此。 此策略意味着，只要群集持续发送请求，AKV 就可能无限期地保持限制状态。 若某些因素导致多个群集同时从 AKV 提取数据，则限制 AKV 的可能性会显著增加。 例如，如果 CI/CD 管道一次性向多个群集的 SSE 配置推送更新，则默认情况下，所有受影响的群集都会尝试立即重新调用。 要避免发生限制，机密的聚合需求量必须显著低于 AKV 的最大容量。

某些部署不太可能导致 AKV 发生限制。 若群集数量乘以每个群集提取的机密数量得出的积远低于 AKV 10 秒事务限制（4,000 次），则不太可能触发限制。 例如，一个包含 20 个群集的部署，每个群集提取 10 个机密，这样的配置不太可能触发 AKV 限制，因为 10×20 远远小于 4,000。 若在这种情况下仍触发限制，请仔细核查同一密钥保管库的其他使用场景以及提取的机密数量。

但是，对于较大规模的部署，例如有 2,000 个群集，每个群集提取 20 个机密，则 AKV 很可能会不时发生限制。 在这种情况下，请考虑启用 jitterSeconds 设置（请参阅 配置参考）。 此设置 jitterSeconds 会在从 SecretSync 资源提取机密之前添加随机延迟，并随着时间的推移在 AKV 上分散部署的负载。 启用 jitterSeconds 后，尝试从 AKV 刷新密钥的最坏情况时间是rotationPollIntervalInSeconds+jitterSeconds。 虽然 jitterSeconds 无法 保证 AKV 不堪重负，但概率可减少到几乎为零。

有多种方法可以选择适当的 jitterSeconds 值，具体取决于希望该值的精确程度。 虽然基本方法适用于许多情况，但我们还提供了针对各种部署方案的建议值表。 如果需要更高的精度，请按照提供的步骤来计算自己的值。

设置 jitterSeconds 的最简单方法是使用最长的可接受时间。

  1. 确定刷新应用程序机密之间的最大可接受时间。 两小时（7,200秒）是一个合理的起点。
  2. 设置为 rotationPollIntervalInSeconds 刷新之间的最短时间，或保留默认的一小时（3,600 秒）。
  3. 用可接受的最大刷新时间（以秒为单位）减去 rotationPollIntervalInSeconds，来计算 jitterSeconds 值。

在此示例中， jitterSeconds 将设置为 3,600 秒。 然后，在上次提取后 1 到 2 小时之间随机从 AKV 提取机密。

对于非常大的部署，请仔细检查所选抖动值是否真实：群集数乘以每个群集提取的机密数必须远远低于 AKV 在你的 jitterSeconds 时间间隔内可以提供的全部机密数量。

降低 AKV 限制概率的其他选项包括：

减少轮询频率

检查 AKV 中是否有更新的机密计入速率限制，其方式与首次提取机密的方式相同。 增加 rotationPollIntervalInSeconds （见 配置参考）可以减少 AKV 的聚合需求。

添加其他密钥保管库

可以添加其他 AKV 实例，以增加每秒可能的机密提取次数。 请注意，Azure 订阅的总限制是单个 AKV 限制的五倍，在所有密钥保管库之间共享。 请参阅 Azure Key Vault 服务限制。

  • Last updated on