排查已连接注册表问题

本文讨论了在为支持 Arc 的 Kubernetes 群集安装或更新已连接注册表扩展时可能会收到的一些常见错误消息。

如何安装已连接注册表扩展

已连接注册表扩展以 Helm 图表的形式发布，并需使用 Helm V3 安装。 已连接注册表扩展的所有组件都安装在 connected-registry 命名空间中。 可使用以下命令来检查扩展状态。

# get the extension status 
az k8s-extension show --name <extension-name>  
# check status of all pods of connected registry extension 
kubectl get pod -n connected-registry    
# get events of the extension 
kubectl get events -n connected-registry   --sort-by='.lastTimestamp'

常见错误

错误：无法重用仍被使用的名称

此错误表示你指定的扩展名称已存在。 如果名称已在使用中，则需要使用另一个名称。

错误：无法在命名空间 connected-registry 中新建内容，因为该命名空间处于终止状态

如果某个卸载操作未完成，而此时触发了另一个安装操作，则会发生此错误。 可以运行 az k8s-extension show 命令来检查扩展的预配状态，并确保在执行其他操作之前已卸载扩展。

错误：下载失败，找不到图表路径

如果指定了错误的扩展版本，则会发生此错误。 需要确保指定的版本存在。 如果希望使用最新版本，则无需指定 --version。

常见方案

情形 1：安装失败，但没有显示错误消息

如果在创建或更新扩展时收到错误消息，则可以通过运行 az k8s-extension list 命令来检查创建失败的位置：

az k8s-extension list \ 
--resource-group <my-resource-group-name> \ 
--cluster-name <my-cluster-name> \ 
--cluster-type connectedClusters

解决方案：重启群集、注册服务提供商或删除并重新安装已连接注册表

若要解决此问题，请尝试执行以下方法：

• 重启 Arc Kubernetes 群集。

• 注册 KubernetesConfiguration 服务提供方。

• 强制删除并重新安装已连接注册表扩展。

情形 2：目标已连接注册表版本不存在

尝试安装已连接注册表扩展以面向特定版本时，你会收到一条错误消息，该消息指出已连接注册表的版本不存在。

解决方案：再次安装受支持的已连接注册表版本

再次尝试安装扩展。 请确保使用受支持的已连接注册表版本。

常见问题

问题：扩展创建停留在正在运行状态

可能性 1：永久性卷声明 (PVC) 问题

• 检查已连接注册表的 PVC 的状态

kubectl get pvc -n connected-registry -o yaml connected-registry-pvc

状态 (status) 下的阶段 (phase) 值应该为“准备就绪 (bound)”。 如果该值未发生变化，依旧是“待处理 (pending)”，请删除该扩展。

• 检查所需的存储类是否位于存储类列表中：

kubectl get storageclass --all-namespaces

• 如果不存在于列表中，请重新创建扩展并添加

--config pvc.storageClassName=”standard”` 

• 或者，这可能是由于没有足够的空间容纳 PVC 造成的问题。 使用参数重新创建扩展

--config pvc.storageRequest=”250Gi”` 

可能性 2：连接字符串不正确

• 检查已连接注册表 Pod 的日志：

kubectl get pod -n connected-registry

• 复制已连接注册表 Pod 的名称（例如：“connected-registry-8d886cf7f-w4prp”）并将其粘贴到以下命令中：

kubectl logs -n connected-registry connected-registry-8d886cf7f-w4prp

• 如果看到以下错误消息，则已连接注册表的连接字符串不正确：

Response: '{"errors":[{"code":"UNAUTHORIZED","message":"Incorrect Password","detail":"Please visit https://aka.ms/acr#UNAUTHORIZED for more information."}]}' 

• 确保已创建 protected-settings-extension.json 文件

cat protected-settings-extension.json

• 可按需重新生成 protected-settings-extension.json

cat << EOF > protected-settings-extension.json  
{ 
"connectionString": "$(az acr connected-registry get-settings \ 
--name myconnectedregistry \ 
--registry myacrregistry \ 
--parent-protocol https \ 
--generate-password 1 \ 
--query ACR_REGISTRY_CONNECTION_STRING --output tsv --yes)" 
} 
EOF

• 更新扩展以加入新的连接字符串

az k8s-extension update \ 
--cluster-name <myarck8scluster> \ 
--cluster-type connectedClusters \ 
--name <myconnectedregistry> \ 
-g <myresourcegroup> \ 
--config-protected-file protected-settings-extension.json

问题：已创建扩展，但已连接注册表未处于“在线”状态

可能性 1：之前的已连接注册表尚未停用

在删除了先前的已连接注册表扩展并为同一个已连接注册表创建新的扩展时，通常会发生这种情况。

• 检查已连接注册表 Pod 的日志：

kubectl get pod -n connected-registry

• 复制已连接注册表 Pod 的名称（例如：“connected-registry-xxxxxxxxx-xxxxx”），并将其粘贴到以下命令中：

kubectl logs -n connected-registry connected-registry-xxxxxxxxx-xxxxx

• 如果看到以下错误消息，则需要停用已连接注册表：

Response: '{"errors":[{"code":"ALREADY_ACTIVATED","message":"Failed to activate the connected registry as it is already activated by another instance. Only one instance is supported at any time.","detail":"Please visit https://aka.ms/acr#ALREADY_ACTIVATED for more information."}]}'

• 运行以下命令来停用：

az acr connected-registry deactivate -n <myconnectedregistry> -r <mycontainerregistry>

几分钟后，系统应该会重新创建已连接注册表 pod，并且错误应该消失。

启用日志记录

• 运行 [az acr connected-registry update] 命令，使用调试日志级别更新已连接注册表扩展：

az acr connected-registry update --registry mycloudregistry --name myacrregistry --log-level debug

• 可以应用以下日志级别来帮助排除故障：

  • Debug 级别提供了用于调试的详细信息。

  • Information 级别提供了用于调试的通用信息。

  • Warning 级别表示潜在问题尚未成为错误，但如果不采取措施，可能会成为错误。

  • Error 级别记录阻止操作完成的错误。

  • None 级别会关闭关闭日志记录，因此不会写入任何日志消息。

• 根据需要调整日志级别以解决问题。

活动选择提供了更多选项，用于在调试已连接注册表问题时调整日志的详细程度。 可以使用以下选项：

已连接注册表日志级别特定于已连接注册表的操作，并确定已连接注册表处理的消息的严重性。 此设置用于管理已连接注册表本身的日志记录行为。

--log-level 用于设置实例上的日志级别。 日志级别用于确定记录器处理的消息的严重性。 通过设置日志级别，可以筛选出低于特定严重性的消息。 例如，如果将日志级别设置为“warning”，则记录器将处理警告、错误和严重消息，但会忽略信息和调试消息。

az cli 日志级别控制 Azure CLI 操作期间输出消息的详细程度。 Azure CLI (az) 为日志级别提供了多种详细程度选项，可以调整这些选项来控制其操作期间的输出信息量：

--verbose 会提高日志的详细程度。 与默认设置相比，可提供更详细的信息，这对于识别问题很有帮助。

--debug 用于启用完整的调试日志。 Debug 级别的日志提供最详细的信息，包括“Verbose”级别提供的所有信息以及用于诊断问题的更多详细信息。

后续步骤