> ## 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 上安装 AutoMQ

> 使用 Docker 在 Azure 上安装 AutoMQ 8.x BYOC 控制台，并完成初始化授权。

## 概述

使用 AutoMQ BYOC 前，需要先在您的 Azure 订阅中安装 AutoMQ 控制台。控制台用于创建、管理和监控 AutoMQ 集群。

从 8.x 开始，AutoMQ 控制台通过 Docker 镜像分发和启动。新建环境请使用本文的 Docker 安装流程。已有 7.x 环境请参考 [Azure BYOC 控制台升级 8.x 版本操作指南](../../appendix/azure-byoc-console-upgrade-to-8.x-guide)。

## 前提条件

开始前，请准备以下资源：

* 一个 Azure Subscription 和 Resource Group。
* 一个 Virtual Network，以及供控制台 VM 使用的 Subnet。该 Subnet 必须能够访问 Docker 镜像仓库和 AutoMQ Cloud；无 Public IP 时请配置 NAT Gateway 或其他出站路径。
* 一个专用于控制台的 User-assigned Managed Identity（Console UAMI）。
* 允许运维人员访问控制台 VM 的 `8080` 端口。请将来源限制为办公网络、堡垒机或其他受控访问路径。

## 操作步骤

### 步骤 1：在 AutoMQ Cloud 注册环境

1. 登录 [AutoMQ Cloud](https://account.automq.cloud)。
2. 创建 Azure BYOC Environment，并按向导填写环境名称、Region 等信息。
3. 复制安装向导生成的完整 Docker 启动命令。

<Tip>
  安装命令包含完整的 Base64 `CONFIG`、`CLOUD_PROVIDER=azure`、初始管理员信息和准确的镜像地址。请直接使用生成的命令，不要解码、拆分或手工拼接 `CONFIG`。
</Tip>

### 步骤 2：准备控制台 VM

#### 检查 VM 基础配置

在已准备的 Subnet 中创建 Ubuntu VM。建议配置如下：

* 至少 2 vCPU、8 GiB Memory 和 20 GiB 系统盘。
* 使用独立持久盘保存控制台数据，将该数据盘挂载到固定 host path，并配置 VM 重启后自动挂载。启动控制台前确认目录存在且 Docker 进程可写。
* VM 可以访问 Docker 镜像仓库、AutoMQ Cloud 和 Azure APIs。
* 运维访问路径可以到达 TCP `8080`。

#### 创建并绑定 Console UAMI

创建专用 Console UAMI，并将它绑定到控制台 VM。以下 Azure CLI 命令供参考：

```bash theme={null}
RESOURCE_GROUP="<console-resource-group>"
IDENTITY_NAME="<console-uami-name>"
VM_NAME="<console-vm-name>"

az identity create --resource-group "$RESOURCE_GROUP" --name "$IDENTITY_NAME"
CONSOLE_UAMI_ID=$(az identity show \
  --resource-group "$RESOURCE_GROUP" \
  --name "$IDENTITY_NAME" \
  --query id -o tsv)
az vm identity assign \
  --resource-group "$RESOURCE_GROUP" \
  --name "$VM_NAME" \
  --identities "$CONSOLE_UAMI_ID"
az vm show --resource-group "$RESOURCE_GROUP" --name "$VM_NAME" --query identity
```

控制台 VM 必须使用此 Console UAMI 作为唯一的 Managed Identity caller。`az vm identity assign` 只会追加 identity，不会移除已有 system-assigned identity 或其他 UAMI。启动前检查最终的 `az vm show` 输出；除非生成的配置明确选择 Console UAMI，否则应移除其他 VM identity。后续 **System Initialization** 权限必须授予此 identity。

#### 安装并启动 Docker

登录 VM，安装并启动 Docker。以下命令以 Ubuntu 为例：

```bash theme={null}
sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl enable --now docker
sudo docker version
```

#### 启动 AutoMQ 控制台

执行步骤 1 中生成的完整 Docker 启动命令。执行前确认命令中的 host mount source 位于已挂载的持久盘，并保持 container target 为 `/root`。否则 VM 重建或系统盘替换会导致控制台数据丢失。

执行后检查容器状态和日志：

```bash theme={null}
sudo docker ps
sudo docker logs -f "<container-name-or-id>"
```

容器正常运行且 `8080` 端口可访问后，即可在浏览器中打开 AutoMQ 控制台。使用安装命令中的初始管理员凭据首次登录，并按页面提示立即重置 bootstrap password。

### 步骤 3：完成 System Initialization

首次登录后，打开 **System Initialization**，使用页面生成的 Terraform 配置为现有 Console UAMI 授权。生成的配置不会创建或替换 Console UAMI。页面展示的角色、scope 和命令是当前版本所需权限的权威来源。

生成的权限遵循以下边界：

| 权限组 | Scope | 用途 |
| - | - | - |
| 基础资源发现 | Subscription | 只读发现 Resource Group、AKS、VM/VMSS、VNet/Subnet、Storage、Private DNS、UAMI 和角色元数据。 |
| Blob 数据访问 | 指定的 Ops 或 Data Blob container | 读写和删除 AutoMQ 使用的 Blob object。 |
| AKS 访问 | 指定的 AKS cluster | 读取 AKS，并获取 `clusterUser` credential；不授予 Kubernetes API 管理权限。 |
| Customer-Provided DNS 记录 | 指定的 Private DNS Zone | 读取 VNet link，并维护 Instance-owned A/CNAME records。 |
| Managed resource 生命周期 | 控制台 Resource Group | 选择 Managed resource 时，创建和维护 Storage、Private DNS、UAMI 和 Federated Identity Credential。 |
| Managed RBAC delegation | Subscription，附带页面生成的 condition | 选择 Managed resource 时，只允许控制台创建 AutoMQ 所需的 role definition 和 ServicePrincipal role assignment。 |

AKS credential access 与 Kubernetes authorization 是两项独立权限。启用 Azure RBAC for Kubernetes Authorization 时，在目标 AKS scope 为 Console UAMI 授予控制台页面要求的 Kubernetes role；未启用时，由集群管理员创建并维护所需的 Kubernetes `ClusterRoleBinding`。两种授权方式详见[部署到 Azure AKS](../../deploy-automq-on-kubernetes/deploy-to-azure-aks)。

只应用页面针对所选资源模式和 scope 生成的权限，然后返回 **System Initialization** 完成验证。后续创建 Instance 时选择的资源可能需要补充精确到具体资源的 scope 权限；不要提前授予，也不要使用 Subscription 级 `Contributor` 替代页面生成的最小权限。

## Terraform 快速体验

如果需要用 Terraform 一次性准备控制台、AKS 和示例资源，可参考 [AutoMQ Azure Terraform 示例](https://github.com/AutoMQ/automq-labs/tree/main/byoc-examples/setup/azure/azure-automq-env)。该示例用于快速体验；用于生产前，请按组织要求收紧网络入口、保护 Terraform state，并复核 custom role 和 scope。

## 后续步骤

* **部署到 AKS**：参考 [部署到 Azure AKS](../../deploy-automq-on-kubernetes/deploy-to-azure-aks) 准备 AKS 和 Azure Workload Identity，然后创建 AutoMQ Instance。
* **通过 WebUI 使用 AutoMQ**：参考 [体验 AutoMQ](../experience-automq) 创建和管理 Instance。
* **通过 Terraform 使用 AutoMQ**：参考 [AutoMQ Terraform Provider](https://registry.terraform.io/providers/AutoMQ/automq/latest/docs) 管理 AutoMQ 资源。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.