> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 部署到Azure AKS
> 在 Azure AKS 上部署 AutoMQ BYOC，兼容 Apache Kafka，并通过云原生架构实现弹性扩展与成本优化。
参考 [概述▸](/zh/automq-cloud/deploy-automq-on-kubernetes/overview)，AutoMQ 支持部署到 Kubernetes 上。本文介绍 AutoMQ 部署到 Azure AKS 平台的安装过程。
本文中提及 AutoMQ 产品服务方、AutoMQ 服务方、AutoMQ，均特指 AutoMQ HK Limited 及其附属公司。
## 选择安装方式
AutoMQ 提供以下两种方式将环境部署到 Azure AKS，请根据实际需求选择适合的安装方式：
| 安装方式 | 说明 |
| ---------------------------------------------- | --------------------------------------------------- |
| [方式一：通过 Terraform 一键安装](#方式一通过-terraform-一键安装) | 使用 AutoMQ 提供的 Terraform 示例工程自动完成环境部署，流程简洁高效，推荐优先使用。 |
| [方式二：通过 Azure 控制台手动安装](#方式二通过-azure-控制台手动安装) | 通过 Azure 门户控制台逐步手动创建和配置所需云资源，适用于需要精细化控制每一步操作的场景。 |
## 方式一：通过 Terraform 一键安装
AutoMQ 提供了一站式 Terraform 示例工程，涵盖 AKS 集群创建、Managed Identity 配置、网络设置、Storage Account 创建及权限授予等全部操作。通过运行 Terraform 即可自动完成环境部署，无需手动逐步操作。
推荐优先使用 Terraform 方式进行部署。该方式可显著减少手动操作步骤，降低配置出错的风险。
### 步骤 1：运行 Terraform 创建云资源并部署控制台
前往 [AutoMQ Terraform 示例工程（Azure）](https://github.com/AutoMQ/automq-labs/tree/main/byoc-examples/setup/azure/azure-automq-env)，按照工程中的 README 指引配置参数并执行 Terraform。Terraform 将自动完成以下操作：
* 创建 AutoMQ 控制台依赖的云资源（Storage Account、Private DNS Zone、Managed Identity 及权限配置等）。
* 创建 AKS 集群及专用节点池。
* 部署 AutoMQ 环境控制台。
执行完成后，Terraform 会输出后续步骤所需的关键信息，请记录 Output 中的各项输出值。
### 步骤 2：登录控制台，完成初始化配置
Terraform 执行完成后，登录 AutoMQ BYOC 控制台，创建部署配置以完成初始化。
1. 登录控制台，录入集群名称等配置，点击下一步。
1. 部署类型：选择 Kubernetes。
2. Kubernetes 集群：填写 AKS 集群的集群名称。
3. AKS Resource Group：填写 AKS 集群所在的 Resource Group。
4. DNS ZoneId：填写用于部署 AutoMQ 的 Private DNS Zone 的 ZoneId。
5. DNS Resource Group：填写用于部署 AutoMQ 的 Private DNS Zone 的 Resource Group。
6. Bucket 名称：填写用于部署 AutoMQ 存储消息的数据 Bucket，支持添加多个 Bucket。
7. Bucket Endpoint：填写用于部署 AutoMQ 存储消息的数据 Bucket 的 Blob Service Endpoint。
1. 填写云资源信息后，参考控制台指引，录入数据面节点池使用的 Managed Identity Client ID，点击下一步预览创建。
2. 预览部署配置信息，**完成创建**。即可前往实例管理页面创建实例。
上述配置所需的全部信息（包括 AKS 集群名称、Resource Group、DNS Zone ID、Storage Account Bucket 名称及 Endpoint、Managed Identity Client ID 等）均可直接从 Terraform 执行完成后的 Output 输出中获取，无需登录 Azure 门户控制台逐一查找。请在执行 `terraform apply` 完成后，参考终端输出的 Output 值进行填写。
## 方式二：通过 Azure 控制台手动安装
本节介绍通过 Azure 门户控制台手动完成环境部署的详细操作步骤。
### 步骤 1：安装环境控制台
参考[概述▸](/zh/automq-cloud/deploy-automq-on-kubernetes/overview)，AutoMQ 支持部署到 AKS 集群。在 AKS 部署模式下，首先仍然需要安装 AutoMQ 控制台，再通过控制台界面操作 AKS，将集群部署到 AKS。
在 Azure 上，推荐通过 ARM 模板安装控制台，参考[Azure 安装环境▸](/zh/automq-cloud/getting-started/install-byoc-environment/install-env-on-azure)。
### 步骤 2：创建 Managed Identity
将 AutoMQ 部署到 AKS 时，AutoMQ 数据面集群需要独立的节点池，该节点池需要绑定独立的 Managed Identity，用于访问云资源的权限验证。因此，在创建 AKS 节点池之前，需要提前创建一个 Managed Identity，并授予 AutoMQ 需要的操作权限。操作步骤如下：
1. 访问[ Managed Identity 控制台](https://portal.azure.com/#browse/Microsoft.ManagedIdentity%2FuserAssignedIdentities)。点击创建。选择如下参数：
* 资源组：建议和 AutoMQ 控制台资源组保持一致。
* 地域：建议和后续部署 AutoMQ 的目标地域保持一致。
AutoMQ 要求环境控制台、AKS、StorageAccount、Private DNS Zone 等云资源位于同一个 Resource Group。如果您的 Resource Group 不一致，则需要额外向 AutoMQ 控制台授权。
1. 点击下一步，**创建 Managed Identity** 。创建完成后，点击该 Managed Identity，点击 Overview，记录 Client ID，在后续步骤 4 创建部署配置时需要填写。
### 步骤 3：创建 AKS 集群
参考[概述▸](/zh/automq-cloud/deploy-automq-on-kubernetes/overview)，用户需要提前创建独立的 AKS 集群分配给 AutoMQ 使用。用户可访问 Azure AKS 产品控制台按下方步骤操作。
1. 登录Azure [AKS 控制台](https://portal.azure.com/#browse/Microsoft.ContainerService%2FmanagedClusters)。点击**创建集群** 。
1. **配置集群基础信息** ，需要关注的配置项，其他配置项保持默认即可。
1. 地域：选择正确的地域。
2. 资源组：选择正确的资源组，建议和控制台、Storage Account、DNS 等保持一致。
3. 可用区：选择 3 个可用区。
4. AKS Pricing Tier： 选择 `Standard` 。
5. Authentication and Authorization：选择 `Local account with Kubernetes RBAC` 。
1. **配置节点池** ，需要为 AutoMQ 设置独占的节点池（可以修改默认生成的节点池或者新建一个独立的节点池），需要修改的配置项参考下方参考值，其他配置建议保持不变。
1. Mode：选择 `User` 模式。
2. Availability zones：建议选择至少 3 个可用区。
3. Node size：参考[概述▸](/zh/automq-cloud/deploy-automq-on-kubernetes/overview)，选择 `Standard D4as v5` 机型。
4. Scale method：选择 `Autoscale` 模式，这样可以根据部署需求自动扩展节点。
5. Minimum node count：建议至少选择 3 个节点。
6. Max pods per node：建议设置 30。
7. Taints：需要添加一个污点配置，key 是 `dedicated` ，值是 `automq` ，效果是 `NoSchedule` 。
1. **配置网络。** 选择目标**Virtual Network 和子网。**
1. Network Configuration：务必选择 `Azure CNI Node Subnet` 模式，确保 Pod 可以直接使用 VNet IP。
2. Bring you own Azure Virtual Network：务必选中和开启。
3. Virtual Network：选择 AutoMQ 需要部署的私有网络。
4. Cluster subnet：选择 AutoMQ 需要部署的子网。
1. **保持其他默认配置，创建 AKS 集群。**
2. **前往** [VMSS 控制台](https://portal.azure.com/#view/Microsoft_Azure_ComputeHub/ComputeHubMenuBlade/~/virtualMachineScaleSetsBrowse)**，查找 AutoMQ 专用节点池对应的 VMSS** ，**关联步骤 2 创建的 Managed Identity** 。
AutoMQ 数据面组件的 Pod 通过扮演 AKS Node 绑定的 Managed Identity 身份，访问 Azure 云资源。
建议根据节点池的名称和资源组过滤找到对应的 VMSS。VMSS 的命名规范是 aks-\{NodePoolName}-xxxx-vmss。
找到对应的 VMSS 后，点击 Security >> Identity 页面，绑定之前创建的 Managed Identity。
1. **为 AKS 集群分配** `Network Contributor` **权限。** 前往 [Virtual Network 控制台](https://portal.azure.com/#view/HubsExtension/AssetMenuBlade/~/virtualnetworks/assetName/NetworkFoundation/extensionName/Microsoft_Azure_Network)，找到当前AKS 所在的 Network，点击 IAM 选项，添加 Role Assignment。
AutoMQ 部署到 AKS 时，需要使用 Load Balancer 作为 Service IP。AKS 创建 LB 之前需要被授权 Network Contributor 权限。
授权时，先选择 `Network Contributor` 角色权限，然后搜索 `System-assigned managed identity` ，选择当前 AKS 集群使用的 Managed Identity。
1. 为 AutoMQ 使用的节点池创建 Placeholder Deployment 用于加速节点故障场景的 Failover 速度。
**工作原理：**
Placeholder Deployment 的作用是在 Kubernetes 集群的节点上部署一个低优先级的“占位符”应用，预先占用若干节点。当 AutoMQ 集群的 Pod 所在节点出现故障时，可以快速抢占该 Placeholder 的节点，实现快速恢复。
部署 Placeholder Deployment 可以通过 kubectl 命令或者 Kubernetes 控制台进行操作。
首先[点击链接](http://download.automq.com/k8s-placeholder/automq-low-priority.yaml)，下载名为 `automq-low-priority.yaml` 的优先级申明文件，执行以下命令，创建优先级申明。
```bash theme={null}
kubectl apply -f automq-low-priority.yaml
```
然后[点击链接](http://download.automq.com/k8s-placeholder/automq-aks-placeholder.yaml)，下载 `automq-aks-placeholder.yaml` 文件。需要根据实际部署的节点池，修改其中的参数：
* `metadata.name` : 建议修改成具有意义的 Placeholder 名称，例如 `placeholder-for-nodegroup-A` 。
* `replicas` : Placeholder pod 预留数量，默认为 1，如果是多可用区部署，建议每个可用区保留 1 台机器，即数量设置为可用区的数量。
* `affinity.nodeAffinity` : 用于选择 Placeholder 部署的节点，需要修改 `matchExpressions` 中的 `key` 和 `values` 来精确匹配 AutoMQ 的节点池。在示例的 yaml 文件中提供 2 个选项筛选节点。
* `kubernetes.azure.com/agentpool` ：在 Azure 上使用 `kubernetes.azure.com/agentpool` 标签筛选指定的节点池。
* `node.kubernetes.io/instance-type` ：在 Azure 上使用 `node.kubernetes.io/instance-type` 标签筛选指定的节点机型。
* `resources` :
* limits 的 CPU 和内存与 AKS 节点池的规格保持一致，例如 2C16G。
* requests 的 CPU 和内存应略小于 AKS 节点池的规格，例如使用 3/4 的资源。这样可以确保 Placeholder Pod 调度到额外节点并独占资源，避免其他 Pod 占用资源后导致实际故障转移时调度失败。
**需要修改的参数片段，参考以下 yaml 文件：**
```yaml theme={null}
metadata:
# TODO: Replace with your custom name
name: {Replace with your custom placeholder deployment name}
spec:
# TODO: Replace with your custom node nums
replicas: 1
spec:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: kubernetes.azure.com/agentpool
operator: In
values:
# TODO: Replace with your custom Node Pool Name
- "Replace with your custom Node Pool Name"
- key: node.kubernetes.io/instance-type
operator: In
values:
# TODO: Replace with your custom Node Pool VM Size
- "Replace with your custom Node Pool VM Size"
containers:
- name: placeholder
resources:
# TODO: Replace with your custom Memory and CPU size
limits:
cpu: 2000m
memory: 16Gi
requests:
cpu: 1000m
memory: 12Gi
```
修改完成后，执行以下命令，安装 Placeholder。
```bash theme={null}
kubectl apply -f automq-aks-placeholder.yaml
```
执行完成后，调用以下命令检查 Placeholder Pod 的状态，确保 Placeholder Pod 状态为 `Running` ，并观察它是否被调度到了期望的节点上。
```bash theme={null}
kubectl get pods -l app=low-priority-placeholder -o wide
```
### 步骤 4：进入环境控制台，创建部署配置
首次进入 AutoMQ BYOC 控制台，需要准备对象存储 Bucket、Private DNS 等资源并创建部署配置，设置 Kubernetes 集群信息和授权才可正常使用。
1. 前往 [Storage Account 控制台](https://portal.azure.com/#browse/Microsoft.Storage%2FStorageAccounts)，创建一个 Blob Container 用于保存数据的 Data Bucket。需要确保 Storage Account 的地域和 AutoMQ 控制台、AKS 等保持一致。
创建完成后，记录当前 Container 名称以及 Blob Sevice Endpoint。
1. 前往 [Private DNS Zone 产品控制台](https://portal.azure.com/#browse/Microsoft.Network%2FprivateDnsZones)，创建一个 Private Zone，用于后续 AutoMQ 实例的接入点解析。需要确保 Zone 的地域和 AutoMQ 控制台、AKS 等保持一致。
注意选择 Virtual Network Links，将 AutoMQ 、AKS 的 Virtual Network 关联到当前 Zone。
1. 登录控制台，录入集群名称等配置，点击下一步。
1. 部署类型：选择 Kubernetes。
2. Kubernetes 集群：填写 AKS 集群的集群名称。
3. AKS Resource Group：填写 AKS 集群所在的 Resource Group。
4. DNS ZoneId：填写用于部署 AutoMQ 的 Private DNS Zone 的 ZoneId。
5. DNS Resource Group：填写用于部署 AutoMQ 的 Private DNS Zone 的 Resource Group。
6. Bucket 名称：填写用于部署 AutoMQ 存储消息的数据 Bucket，支持添加多个 Bucket。
7. Bucket Endpoint：填写用于部署 AutoMQ 存储消息的数据 Bucket，支持添加多个 Bucket。
1. 填写云资源信息后，参考控制台指引，对数据面节点池使用的 Managed Identity （即步骤 2 创建的 Managed Identity ClientID）进行授权。授权操作如下：
**前往** [Managed Identity 控制台](https://portal.azure.com/#browse/Microsoft.ManagedIdentity%2FuserAssignedIdentities)**，** 找到步骤 2 的 Managed Identity\*\*，点击 IAM 选项\*\* ，进入 Role assignments 菜单。为该 Managed Identity 授予**Contributor 角色权限** 。
选择前面创建的 Managed Identity，完成授权。
前往 [Storage Account 控制台](https://portal.azure.com/#view/HubsExtension/BrowseResource.ReactView/resourceType/Microsoft.Storage%2FStorageAccounts)，点击 IAM 选项，继续为当前 Managed Identity 授予 `Storage Blob Data Contributor` 的权限。
授权完成后，填写当前 Managed Identity 的 ClientID，点击下一步预览创建。
1. 预览部署配置信息，**完成创建** 。即可前往实例管理页面创建实例。