排查 Azure Stack Hub 上的 AKS 引擎问题

2025-07-07

在 Azure Stack Hub 上部署或使用 AKS 引擎时，可能会遇到问题。本文介绍了对 AKS 引擎的部署进行故障排除的步骤。收集有关 AKS 引擎的信息，收集 Kubernetes 日志，并查看自定义脚本扩展错误代码。还可以为 AKS 引擎打开 GitHub 议题。

注释

对于 AKSe 版本 0.75.3 及更高版本，下面的 aks-engine 命令将以 aks-engine-azurestack 开头，而不是 aks-engine。

排查 AKS 引擎安装问题

如果以前的安装步骤失败，可以使用 GoFish 包管理器安装 AKS 引擎。 GoFish 将自己描述为跨平台 Homebrew。

可在此处找到有关使用 GoFish 安装 AKS 引擎的说明。

收集节点和群集日志

可以在检索节点和群集日志中找到有关收集节点和群集日志的说明。

先决条件

本指南假定你已下载 Azure CLI 和 AKS 引擎。

本指南还假定你已使用 AKS 引擎部署群集。有关详细信息，请参阅在 Azure Stack Hub 上使用 AKS 引擎部署 Kubernetes 群集。

检索日志

该 aks-engine get-logs 命令可用于排查群集问题。该命令将生成、收集和下载一组文件到工作站。这些文件包括节点配置、群集状态和配置，以及设置日志文件。

在高级别上：该命令的工作原理是将 SSH 会话建立到每个节点，执行收集并压缩相关文件的日志收集脚本，并将.ZIP文件下载到本地计算机。

SSH 身份验证

需要有效的 SSH 私钥才能建立群集 Linux 节点的 SSH 会话。 Windows 凭据存储在 API 模型中，并从那里加载。设置为 windowsprofile.sshEnabled true 以在 Windows 节点中启用 SSH。

将日志上传到存储帐户容器

成功检索群集日志后，如果设置了可选参数 --upload-sas-url ，AKS 引擎就可以将它们保存在 Azure 存储帐户容器上。 AKS 引擎要求容器名称是提供的 SAS URL 的一部分。预期格式为 https://{blob-service-uri}/{container-name}?{sas-token}.

注释

尚不支持使用 AD FS 标识提供者的自定义云上的存储帐户。

无法加入群集的节点

默认情况下， aks-engine get-logs 从已成功加入群集的节点收集日志。若要从无法加入群集的 VM 收集日志，请设置标志 --vm-names：

--vm-name k8s-pool-01,k8s-pool-02

aks-engine get-logs 的用法

假设您已部署群集，并且最初用于部署该群集的 API 模型存储在_output/<dnsPrefix>/apimodel.json，那么您可以通过运行如下命令来收集日志：

aks-engine get-logs \
    --location <location> \
    --api-model _output/<dnsPrefix>/apimodel.json \
    --ssh-host <dnsPrefix>.<location>.cloudapp.chinacloudapi.cn \
    --linux-ssh-private-key ~/.ssh/id_rsa

参数

参数	必需	说明
--位置	是的	群集资源组的 Azure 位置。
--api-model	是的	群集生成的 API 模型的路径。
--ssh-host	是的	可访问群集中所有节点的 SSH 侦听器的 FQDN 或 IP 地址。
--linux-ssh-private-key	是的	可用于在群集 Linux 节点上创建远程会话的 SSH 私钥的路径。
--output-directory	否	输出目录，从 `--api-model` 派生（如果缺少）。
--control-plane-only	否	仅从控制平面节点收集日志。
--vm-names	否	仅从指定的 VM（逗号分隔的名称）收集日志。
--upload-sas-url	否	用于上传收集的日志的 Azure 存储帐户 SAS URL。

查看自定义脚本扩展错误代码

AKS 引擎为每个 Ubuntu 服务器生成一个脚本作为自定义脚本扩展（CSE）的资源来执行部署任务。如果脚本引发错误，它将在/var/log/azure/cluster-provision.log中记录错误。错误会在门户网站上显示。错误代码可能有助于找出问题案例。有关 CSE 退出代码的详细信息，请参阅 cse_helpers.sh。

向 Azure 支持工程师提供 Kubernetes 日志

如果在收集和检查日志后仍无法解决问题，可能需要开始创建支持票证并提供收集的日志的过程。

作员可以将生成的日志与 Azure 支持可能需要的其他系统日志组合在一起。作员可以将其提供给 Azure。

可以通过多种方式提供 Kubernetes 日志：

您可以联系您的 Azure Stack Hub 运营商。您的操作员使用存储在.ZIP文件中的日志信息来创建技术支持案例。
如果存储帐户的 SAS URL 可用于上传 Kubernetes 日志，则可以使用 SAS URL 添加以下命令和标志，以将日志保存到存储帐户：
```
aks-engine get-logs -upload-sas-url <SAS-URL>
```
有关说明，请参阅将日志上传到存储帐户容器。
如果你是云服务运营商，则可以：
- 使用 Azure Stack Hub 管理门户中的 “帮助 + 支持 ”边栏选项卡上传日志。有关说明，请参阅立即使用管理员门户发送日志。
- 使用 Privileged End Point（PEP）运行 PowerShell cmdlet Get-AzureStackLog。有关说明，请参阅使用 PowerShell 立即发送日志。

提交 GitHub 问题

如果无法解决部署错误，可以打开 GitHub 问题。

在 AKS 引擎存储库中打开 GitHub 问题。
使用以下格式添加标题：CSE 错误： exit code <INSERT_YOUR_EXIT_CODE>。
在问题中包含以下信息：
- 用于部署群集的群集配置文件 apimodel.json。在 GitHub 上发布机密和密钥之前，请删除所有机密和密钥。
- 以下 kubectl 命令 get nodes的输出。
- 运行不正常的节点中 /var/log/azure/cluster-provision.log 的内容。

后续步骤

了解 Azure Stack Hub 上的 AKS 引擎。

通过