使用 AKS 引擎在 Azure Stack Hub 上部署 Kubernetes 群集

2025-07-07

可以通过运行 AKS 引擎的客户端 VM 在 Azure Stack Hub 上部署 Kubernetes 群集。本文介绍如何编写群集规范、使用 apimodel.json 文件部署群集，以及如何通过 Helm 部署 MySQL 来检查群集。

定义群集规范

可使用称为 API 模型的 JSON 格式在文档文件中指定群集规范。 AKS 引擎在 API 模型中使用群集规范来创建群集。

可以在 AKS 引擎和相应映像映射中找到最新发布版的 OS 和 AKS 引擎版本号所对应的 API 模型示例。

在表中查找 AKS 引擎版本号，例如 v.0.63.0。
在 API 模型示例表中，选择并打开 OS 的链接。
选择“Raw”。可以使用以下说明中的 URL。

API 模型的 URL 可能如下所示：

https://raw.githubusercontent.com/Azure/aks-engine-azurestack/master/examples/azure-stack/kubernetes-azurestack.json

对于以下每个示例，请用相应的URL替换<URL for the API Model>。

更新 API 模型

本部分介绍如何为群集创建 API 模型。

首先使用适用于 Linux 或 Windows 的 Azure Stack Hub API 模型文件。在安装 AKS 引擎的计算机上运行：
```
curl -o kubernetes-azurestack.json <URL for the API Model>
```
注意

如果已断开连接，可以下载该文件，并将其手动复制到计划在其上编辑文件的已断开连接的计算机。可以使用 PuTTY 或 WinSCP 等工具将文件复制到 Linux 计算机。
若要在编辑器中打开 API 模型，可以使用 nano：
```
nano ./kubernetes-azurestack.json
```
注意

如果尚未安装 nano，可在 Ubuntu 上安装 nano：sudo apt-get install nano。
在 kubernetes-azurestack.json 文件中找到 orchestratorRelease 和 orchestratorVersion。请参考发行说明中的版本表，选择一个受支持的 Kubernetes 版本。将 orchestratorRelease 指定为 x.xx，将 orchestratorVersion 指定为 x.xx.x。有关当前版本的列表，请参阅受支持的 AKS 引擎版本
找到 customCloudProfile 并提供租户门户的 URL。例如，https://portal.local.azurestack.external。
如果使用的是 AD FS，请添加 "identitySystem":"adfs"。例如，
```
    "customCloudProfile": {
        "portalURL": "https://portal.local.azurestack.external",
        "identitySystem": "adfs"
    },
```
注意

如果为标识系统使用 Microsoft Entra ID，则无需添加 identitySystem 字段。

在 masterProfile 中设置以下字段：

字段	说明
dns前缀	输入用于标识 VM 主机名的唯一字符串。例如基于资源组名称的名称。
计数	输入要用于部署的主机数。 HA 部署的最小使用数为 3，非 HA 部署的最小使用数可为 1。
vmSize	输入 Azure Stack Hub 支持的大小，例如 `Standard_D2_v2`。
发行版	输入 `aks-ubuntu-18.04` 或 `aks-ubuntu-20.04`。

在 agentPoolProfiles中，更新：

字段	说明
计数	输入要用于部署的代理数。每个订阅使用的节点的最大数目为 50 个。如果要为每个订阅部署多个群集，请确保代理总数不超过 50 个。请确保使用示例 API 模型 JSON 文件中指定的配置项目。
vmSize	输入 Azure Stack Hub 支持的大小，例如 `Standard_D2_v2`。
发行版	输入 `aks-ubuntu-18.04`、`aks-ubuntu-20.04` 或 `Windows`。将 `Windows` 用于在 Windows 上运行的代理。例如，请参阅 kubernetes-windows.json

在 linuxProfile中，更新：

字段	说明
管理员用户名	输入 VM 管理员用户名。
SSH	输入将用于 VM 的 SSH 身份验证的公钥。依次使用 `ssh-rsa` 和密钥。有关创建公钥的说明，请参阅为 Linux 创建 SSH 密钥。

如果要部署到自定义虚拟网络，可以找到有关在将 Kubernetes 群集部署到自定义虚拟网络的 API 模型中的相应数组中查找和添加所需键和值的说明。

注意

Azure Stack Hub 的 AKS 引擎不允许你提供自己的证书来创建群集。

如果使用的是 Windows，请在 windowsProfile 中更新 adminUsername: 和 adminPassword 的值：
```
"windowsProfile": {
"adminUsername": "azureuser",
"adminPassword": "",
"sshEnabled": true
}
```

有关 API 模型的详细信息

有关 API 模型中所有可用选项的完整参考，请参阅群集定义。
有关 Azure Stack Hub 的特定选项的亮点，请参阅 Azure Stack Hub 群集定义细节。

部署 Kubernetes 群集

收集 API 模型中的所有必需值后，可以创建群集。此时，您应要求 Azure Stack Hub 操作员：

验证系统的运行状况，建议运行 Test-AzureStack 和 OEM 供应商的硬件监视工具。
验证系统容量，包括内存、存储和公共 IP 等资源。
提供与你的订阅关联的配额的详细信息，以便验证是否有足够的空间来容纳你计划使用的 VM 数量。

继续部署群集：

查看 Azure Stack Hub CLI 标志上 AKS 引擎的可用参数。

参数	示例	说明
azure-env	AzureStackCloud	若要向 AKS 引擎指示目标平台是 Azure Stack Hub，请使用 `AzureStackCloud`。
身份系统	adfs	可选。如果使用 Active Directory 联合身份验证服务 (AD FS)，请指定标识管理解决方案。
位置	本地的	Azure Stack Hub 的区域名称。
资源组	kube-rg	输入新资源组的名称，或者选择现有资源组。资源名称必须为字母数字，且必须小写。
API模型	./kubernetes-azurestack.json	群集配置文件的路径或 API 模型。
输出目录	kube-rg	输入要包含输出文件 apimodel.json 以及其他已生成文件的目录的名称。
客户端ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入服务主体 GUID。 Azure Stack Hub 管理员创建服务主体时标识为应用程序 ID 的客户端 ID。
客户端密钥	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入服务主体密码。在创建服务时设置的客户端密码。
订阅编号	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入订阅 ID。必须提供租户的订阅。不支持部署到管理订阅。有关详细信息，请参阅订阅套餐

以下是示例：

注意

对于 AKSe 0.75.3 及更高版本，部署 AKS 引擎群集的命令为 aks-engine-azurestack deploy。

aks-engine deploy \
--azure-env AzureStackCloud \
--location \
--resource-group kube-rg \
--api-model ./kubernetes-azurestack.json \
--output-directory kube-rg \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--identity-system adfs # required if using AD FS

如果由于某种原因，输出目录在创建后执行失败，可以更正此问题并重新运行该命令。如果之前重新运行部署并使用同一输出目录，AKS 引擎将返回一个错误，指出该目录已存在。可以使用标志 --force-overwrite覆盖现有目录。
将 AKS 引擎群集配置保存在安全、已加密的位置。

找到文件 apimodel.json。将其保存到安全位置。此文件用作所有其他 AKS 引擎操作中的输入。

生成的 apimodel.json 文件包含输入 API 模型中使用的服务主体、机密和 SSH 公钥。此文件还包含 AKS 引擎执行所有其他操作所需的所有其他元数据。如果丢失文件，AKS 引擎无法配置群集。

机密未加密。将该文件保存在已加密的安全位置。

验证群集

检查群集的方法是先连接到 kubectl，获取信息，然后获取节点的状态。

获取 kubeconfig 文件以连接到控制平面。
- 如果已安装 kubectl，请在 kubeconfig 目录路径中检查 /kubeconfig/kubeconfig.json 文件中是否有新创建的群集。可以将 /kubeconfig.json 添加到 .kube 目录，并将其重命名为“config”来访问新群集。
  如果尚未安装 kubectl，请参阅安装工具以安装 Kubernetes 命令行工具。否则，请按照这些说明从其中一个控制平面节点访问群集。
使用 Azure Stack Hub 门户获取其中一个控制平面节点的公共 IP 地址。
在可访问 Azure Stack Hub 实例的计算机上，使用客户端（如 PuTTY 或 MobaXterm）通过 SSH 连接到新的控制平面节点。
对于 SSH 用户名，请使用azureuser以及您为群集部署时提供的密钥对的私钥文件。

检查群集终结点是否正在运行：

kubectl cluster-info

输出应如下所示：

Kubernetes master is running at https://democluster01.location.domain.com
CoreDNS is running at https://democluster01.location.domain.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://democluster01.location.domain.com/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

然后查看节点状态：

kubectl get nodes

输出应如下所示：

k8s-linuxpool-29969128-0   Ready      agent    9d    v1.15.5
k8s-linuxpool-29969128-1   Ready      agent    9d    v1.15.5
k8s-linuxpool-29969128-2   Ready      agent    9d    v1.15.5
k8s-master-29969128-0      Ready      master   9d    v1.15.5
k8s-master-29969128-1      Ready      master   9d    v1.15.5
k8s-master-29969128-2      Ready      master   9d    v1.15.5

排查群集部署问题

如果在使用 AKS 引擎部署 Kubernetes 群集时遇到错误，可以检查：

是否使用了正确的服务主体凭据 (SPN)？
SPN 是否具有对 Azure Stack Hub 订阅的“参与者”角色？
Azure Stack Hub 计划中是否有足够大的配额？
Azure Stack Hub 实例是否正在应用修补程序或进行升级？

有关详细信息，请参阅 Azure/aks-engine-azurestack GitHub 存储库中的故障排除一文。

轮换服务主体机密

使用 AKS 引擎部署 Kubernetes 群集后，服务主体 (SPN) 会用于管理与 Azure Stack Hub 实例上的 Azure 资源管理器的交互。在某些时候，此服务主体的机密可能会过期。如果机密过期，可以通过以下方式刷新凭据：

使用新的服务主体机密更新每个节点。
或更新 API 模型凭据并运行升级。

手动更新每个节点

从云运营商处获取服务主体的新机密。有关 Azure Stack Hub 的说明，请参阅使用应用标识访问 Azure Stack Hub 资源。
使用云运营商提供的新凭据更新每个节点上的 /etc/kubernetes/azure.json。进行更新后，重启 kubele 和 kube-controller-manager。

使用 aks-engine update 更新群集

或者，可以使用更新的 .json 文件将 apimodel.json 中的凭据替换为同一个或更新的 Kubernetes 版本，并运行升级。有关升级模型的说明，请参阅升级 Azure Stack Hub 上的 Kubernetes 群集

后续步骤

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

通过