> ## 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.

# 在 Google Cloud 上安装 AutoMQ

> 本文介绍如何在 Google Cloud 上通过 Docker 安装 AutoMQ 控制台，并完成初始权限配置，为后续部署 GKE 集群做准备。

## 概述

在 Google Cloud 上使用 AutoMQ BYOC 环境时，您首先需要安装 AutoMQ 控制台。控制台是部署在您 Google Cloud 项目中的 Web 应用，您将通过它来创建、管理和监控 AutoMQ 集群。

从 8.x 版本开始，AutoMQ 控制台通过 Docker 镜像分发和启动。新环境建议使用 Docker 安装方式。

## 前置条件

在开始安装 AutoMQ 控制台之前，请确保已经准备好基础的 Google Cloud 网络资源。

* **VPC 环境**：AutoMQ 控制台和 GKE 集群需要运行在您的 VPC 中，通常应与 Kafka 客户端应用部署在相同 VPC 或可连通的 VPC 中。

## 操作步骤

### 步骤 1：在 AutoMQ 官网注册环境

首先，您需要在 AutoMQ 官网注册部署环境，以获取环境安装元信息和 Docker 启动命令。

1. 访问 [AutoMQ Cloud](https://account.automq.cloud)，登录您的账户。
2. 在控制台页面，点击 **创建环境**。
3. 根据向导填写环境名称、云厂商、地域等信息。
4. 完成创建后，复制安装向导中生成的 Docker 启动命令。

### 步骤 2：准备控制台 VM 并部署控制台

AutoMQ 控制台需要部署在一台独立的 Google Cloud VM 上。该 VM 应位于后续部署 GKE 集群所使用的 VPC 中。

在 GCP 中，运行在 VM 上的 AutoMQ 控制台通过 VM 绑定的 Google Service Account 调用 Google Cloud API。为避免使用默认 Compute Engine 服务账号，建议在创建 VM 前，先在控制台所在的 Service Project 中创建一个专用服务账号；本文后续称为“控制台 Google Service Account”。

控制台 Google Service Account 是 AutoMQ 控制台的控制面身份。后续初始化权限时，您会把 GKE、GCS、Cloud DNS、IAM binding 等管理权限授予这个服务账号，使控制台可以代表您创建和管理 AutoMQ 所需的云资源。此时只需要先创建该服务账号并在创建 VM 时绑定它，不需要提前授予完整的 AutoMQ 权限。控制台启动后，初始化页面会展示需要授予给该服务账号的权限，并引导您完成授权和验证。

如果使用 `gcloud` 创建控制台 Google Service Account，可以参考如下命令：

```bash theme={null}
PROJECT_ID="<service-project-id>"
CONSOLE_SA_ID="automq-console"

gcloud iam service-accounts create "${CONSOLE_SA_ID}" \
  --project="${PROJECT_ID}" \
  --display-name="AutoMQ console"
```

#### 基本要求

为确保控制台稳定运行，建议控制台 VM 满足以下要求：

1. **实例规格**
   * 至少 **2 核 CPU** 和 **8 GB 内存**。
   * 系统盘至少 **20 GiB**。
   * 建议为控制台数据准备独立数据盘或稳定的数据目录。

2. **网络位置**

   * 控制台 VM 应位于后续 GKE 集群可访问的 VPC 和子网中。
   * 如果使用 Shared VPC，请确认控制台所在 Service Project 与 VPC 所在 Host Project 的权限边界。
   * 控制台服务默认监听 `8080` 端口。请在防火墙规则中允许您的运维访问来源访问控制台 VM 的 `8080` 端口，并根据实际办公网络或跳板机网段收敛来源 CIDR。

   如需通过 `gcloud` 创建防火墙规则，可参考如下命令。该示例通过 `--target-service-accounts` 将目标收敛到绑定了控制台 Google Service Account 的 VM。`NETWORK_PROJECT_ID` 是 VPC 和防火墙规则所在项目；非 Shared VPC 场景下通常就是 Service Project。

   ```bash theme={null}
   NETWORK_PROJECT_ID="<network-project-id>"
   VPC_NAME="<vpc-name>"
   CONSOLE_SA_EMAIL="<console-service-account-email>"
   SOURCE_CIDR="<operator-source-cidr>"

   gcloud compute firewall-rules create "automq-console-allow-8080" \
     --project="${NETWORK_PROJECT_ID}" \
     --network="${VPC_NAME}" \
     --direction=INGRESS \
     --action=ALLOW \
     --source-ranges="${SOURCE_CIDR}" \
     --target-service-accounts="${CONSOLE_SA_EMAIL}" \
     --rules=tcp:8080
   ```

3. **公网访问或出网能力**
   * 控制台 VM 需要能够拉取 Docker 镜像并同步必要元数据。可以通过公网 IP、Cloud NAT 或其他出网方式实现。
   * 如果控制台 VM 不配置公网 IP，也没有通过 Cloud NAT 或其他方式提供出网能力，请为控制台 VM 所在子网启用 Private Google Access，使 VM 可以访问 Cloud Storage、GKE、IAM、Cloud DNS 等 Google APIs。该配置只覆盖 Google API 访问；如果需要访问外部镜像仓库等非 Google 端点，仍需要公网 IP、Cloud NAT 或其他出网路径。可参考 Google Cloud 官方文档[《配置 Private Google Access》](https://docs.cloud.google.com/vpc/docs/configure-private-google-access)。

4. **VM 服务账号**
   * 创建 VM 时，将前面准备的控制台 Google Service Account 绑定到该 VM。这里绑定的是本步骤开始时创建的同一个服务账号，后续权限初始化也会围绕它完成。
   * 创建 VM 的操作者需要具备对该服务账号的 `iam.serviceAccounts.actAs` 权限，才能将该服务账号绑定到 VM。
   * 将 VM 的访问范围设置为允许访问所有 Cloud APIs（`https://www.googleapis.com/auth/cloud-platform`）。Google Cloud 的默认访问范围只包含 Cloud Storage 只读、Logging、Monitoring 等有限权限。
   * 即使控制台 Google Service Account 已具备 IAM 权限，VM 访问范围不足仍可能导致控制台无法调用 GKE、IAM、Cloud DNS 或写入 GCS。可参考 Google Cloud 官方文档[《创建使用用户管理的服务账号的虚拟机》](https://docs.cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)。

#### 安装并启动 Docker

登录控制台 VM，安装并启动 Docker。以下命令以 Debian / Ubuntu 系统为例：

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

#### 启动 AutoMQ 控制台

VM 准备完成后，复制步骤 1 中安装向导生成的 Docker 启动命令，启动 AutoMQ 控制台。

<Tip>
  安装向导生成的命令已经包含环境 ID、云厂商、地域、认证参数、Docker 镜像地址等信息。请不要手工拼接这些参数。
</Tip>

执行启动命令后，检查容器状态和日志：

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

观察到 Docker 容器正常运行，且 8080 端口正常联通，即可通过浏览器访问 AutoMQ 控制台。

### 步骤 3：配置控制台权限并完成初始化

AutoMQ 控制台启动成功后，首次登录时可能会提示需要初始化权限。请按照页面中的 GCP 权限说明，为控制台 Google Service Account 补齐授权。

权限初始化的目的是让 AutoMQ 控制台获得创建和管理云资源所需的权限。在 GCP 中，控制台 VM 通过绑定的控制台 Google Service Account 调用 Google Cloud API；您需要按页面提示，将权限授予这个服务账号。控制台会在初始化时验证这些权限是否已生效。

GCP 的授权位置会随能力不同而变化。非 Shared VPC 场景下，Service Project 和 Host Project 通常是同一个项目；Shared VPC 场景下，GKE、控制台 VM、Bucket、Google Service Account 等资源通常位于 Service Project，VPC/Subnet/Firewall 等网络资源位于 Host Project。部分 Bucket 和 Cloud DNS 权限也可能需要授予在具体资源上。下表用于帮助理解初始化页面展示的 binding，实际授权请以页面生成的内容为准。

| 能力                           | 推荐授权位置                                       | 说明                                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 控制台系统数据管理                    | 初始化页面展示的 Bucket                              | 控制台需要读写系统日志、Metrics 等运行数据，并维护对应 Bucket IAM policy。推荐授予 `roles/storage.admin`。                                                                                                                                                                                                                                                     |
| GKE 与网络读取                    | Service Project 和 Host Project               | 控制台需要读取 GKE Standard 集群、节点池、VPC 和 Subnet。Shared VPC 场景下，VPC/Subnet 读取权限应授予 Host Project。因此需在 Service Project 授予 `roles/container.admin`，并在网络所在 Project 授予 `roles/compute.networkViewer`。                                                                                                                                          |
| 数据 Bucket 管理                 | Service Project                              | 控制台需要按实例配置创建托管数据 Bucket，或发现和校验已有数据 Bucket。托管 Bucket 模式推荐授予 `roles/storage.admin`；使用已有 Bucket 时通常需要 `roles/storage.bucketViewer`。                                                                                                                                                                                                  |
| Cloud DNS 管理                 | Service Project；Shared VPC 时还涉及 Host Project | 控制台需要创建或读取 Cloud DNS private managed zone，并在托管 DNS 模式下维护 zone IAM policy。托管 DNS 模式需要 `roles/dns.admin`，并创建自定义角色 `automqConsoleDnsZoneIamPolicyAdmin`，包含 `dns.managedZones.getIamPolicy` 和 `dns.managedZones.setIamPolicy`。Shared VPC 场景下，Host Project 还需要 `roles/dns.admin` 用于 private zone 绑定；使用已有 DNS 时通常需要 `roles/dns.reader`。 |
| 实例 Google Service Account 管理 | Service Project                              | 控制台需要在托管身份模式下创建实例 Google Service Account，并配置实例级 IAM binding；使用已有身份时需要读取目标 Google Service Account。托管身份模式需要 `roles/iam.serviceAccountAdmin`、`roles/iam.roleAdmin` 和 `roles/resourcemanager.projectIamAdmin`；使用已有身份时通常需要 `roles/iam.serviceAccountViewer`。                                                                           |

完成授权后，返回 AutoMQ 控制台点击验证或继续初始化。验证通过后，您就可以进入 AutoMQ 控制台并继续配置 GKE 集群。

## 后续步骤

* **部署到 GKE**：完成控制台安装和权限初始化后，请参考 [部署到 Google Cloud GKE](/zh/automq-cloud/deploy-automq-on-kubernetes/deploy-to-google-cloud-gke)。
* **通过 WebUI 使用 AutoMQ**：继续通过环境控制台创建实例，并体验产品功能。[体验 AutoMQ▸](/zh/automq-cloud/getting-started/experience-automq)
* **通过 Terraform 使用 AutoMQ**：安装控制台后，用户可以通过 AutoMQ Terraform Provider 管理和使用 AutoMQ。通过 Terraform 方式使用 AutoMQ，请参考 [Terraform Provider 文档](https://registry.terraform.io/providers/AutoMQ/automq/latest/docs)。