> ## 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.
# Kubernetes 部署多节点集群
> 在 Kubernetes 上部署多节点 AutoMQ 集群，完全兼容 Kafka API，支持云原生高效运维。
本主题介绍如何基于 Kubernetes 部署多节点的 AutoMQ 集群，用户可在该开发环境中验证例如分区迁移、数据自动均衡等集群相关的功能特性。
除了 Kubernetes 部署方案，用户可参考以下文档体验其他部署方案：
* [Linux 主机部署多节点集群▸](/zh/automq/deployment/deploy-multi-nodes-cluster-on-linux)
面向生产环境负载的 AutoMQ 部署和参数调优相对复杂，您可以通过[此处表单](https://www.automq.com/contact)联系 AutoMQ 团队获取必要的协助和最佳实践。
此外，如果您期望完全避免安装部署的工作负担，可以通过以下链接体验 AutoMQ 团队提供的全托管云服务，当前各云市场均提供了免费 30 天的试用体验。
* [从 AWS Marketplace 免费体验 AutoMQ Cloud](https://docs.automq.com/automq-cloud/getting-started/install-byoc-environment/aws/install-automq-on-aws)。
* [从阿里云云市场体验 AutoMQ Cloud](https://docs.automq.com/zh/automq-cloud/getting-started/install-byoc-environment/alibaba-cloud)。
## 前提条件
本文档示例用于部署一个 5 节点的 AutoMQ 集群，其中 3 个节点运行 Controller 和 Broker，剩余 2 个节点仅运行 Broker。
需要提前检查如下条件：
* 准备好一个Kubernetes集群，确保至少有5个 Node ，推荐 4 核 16GB 内存的网络优化型虚拟机，后续在上面进行 Pod 创建等。
* Helm chart 确保版本在v3.8.0及以上。参考 [Helm Chart 快速入门](https://helm.sh/docs/intro/quickstart/) 。
* 使用Bitnami Helm仓库。AutoMQ 完全兼容 Bitnami 的 Helm Charts，因此您可以基于 Bitnami 的相关 values.yaml 自定义 AutoMQ Kubernetes 集群。
* 准备2个对象存储的 Bucket，一个用于存储消息数据，一个用于存储系统日志和 Metric 数据。
## 部署 AutoMQ 集群
### 第 1 步：编辑配置文件
创建空的 `automq-values.yaml` 文件，编辑文件并添加特定参数。您可以参考 [demo-values.yaml](https://github.com/AutoMQ/automq-labs/blob/main/opensource-examples/setup/kubernetes/bitnami/demo-values.yaml)及其子目录下不同场景的推荐配置样例，更多细节参考[ README.md](https://github.com/AutoMQ/automq-labs/blob/main/opensource-examples/setup/kubernetes/bitnami/README.md)。
* 需要将 `${ops-bucket}` 、 `${data-bucket}` 、 `${region}` 、 `${endpoint}` 替换成对象存储的具体值，详情参见 [对象存储配置▸](/zh/automq/configuration/object-storage-configuration) 。
* 将 `${access-key}` 和 `${secret-key}` 替换成实际的值。你也可以选择 IAM Role 等其他授权方式。
* 推荐生产级别的 AutoMQ 独占节点部署（避免和其他 Pod 争抢网络带宽等资源），建议通过节点亲和性（nodeAffinity）和容忍度（tolerations）的标签进行匹配。
* 多可用区部署，可使用 `topologySpreadConstraints` 参数确保 Pod 在指定可用区间均匀分布。
```yaml theme={null}
controller:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: "topology.kubernetes.io/zone"
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
app: automq
```
* 避免跨可用区流量， `brokerRackAssignment` 最终会设置 AutoMQ Broker 的 `broker.rack` ，客户端配合做设置 [客户端配置▸](/zh/automq/eliminate-inter-zone-traffics/client-configuration)，最终达到消除跨可用区流量费用的效果。如在 AWS EKS 可作如下设置：
```yaml theme={null}
brokerRackAssignment: aws-az
```
* 其他的一些服务端参数可在 `controller.extraConfig` 和 `broker.extraConfig` 按需设置。详情请参见： [Broker 和 Controller 配置▸](/zh/automq/configuration/broker-and-controller-configuration) 。
### 第 2 步：安装AutoMQ
使用自定义 YAML 文件安装或升级 AutoMQ Helm Chart：建议安装 AutoMQ 时使用 `--version` 指定[ 31.x.x（31.1.0 ～ 31.5.0）](https://artifacthub.io/packages/helm/bitnami/kafka)版本的 Bitnami Helm Chart。
```bash theme={null}
helm install automq-release oci://registry-1.docker.io/bitnamicharts/kafka -f demo-values.yaml --version 31.5.0 --namespace automq --create-namespace
```
等待 AutoMQ 集群就绪：
```bash theme={null}
kubectl --namespace automq rollout status statefulset --watch
```
当 AutoMQ 集群就绪时，输出应类似以下内容：
```text theme={null}
statefulset rolling update complete 2 pods at revision automq-kafka-broker-6c756696dd...
statefulset rolling update complete 3 pods at revision automq-kafka-controller-c574d5fd5...
```
查看 Pod列表：
```text theme={null}
~/.kube kubectl get pods
NAME READY STATUS RESTARTS AGE
data-automq-kafka-controller-0 1/1 Running 0 16m
data-automq-kafka-controller-1 1/1 Running 0 16m
data-automq-kafka-controller-2 1/1 Running 0 16m
data-automq-kafka-broker-0 1/1 Running 0 13m
data-automq-kafka-broker-0 1/1 Running 0 13m
```
## 测试消息收发
Helm 执行完成后会输出集群的访问地址和测试收发的命令，可基于 `kafka-console-producer.sh` 、 `kafka-console-consumer.sh` 进行 Topic 发送、消费消息测试。
## 停止并卸载 AutoMQ 集群
* 在完成测试后，可通过 `helm uninstall` 停止并卸载 AutoMQ 集群。
```bash theme={null}
helm uninstall automq-release -n automq
```
* 若历史数据不再需要，需将集群的 PVC、Bucket 数据一并删除，防止脏数据影响下一次部署。
## 生产环境注意事项
### 固定 Chart 版本
为避免部署意外变更，建议固定 Helm Chart 版本。固定版本指在部署时指定确切版本，而非使用最新或未指定版本。固定 Helm Chart 版本有助于：
* **确保兼容性** ：确保部署的应用行为与测试一致，不受新 Chart 版本发布的影响。
* **避免意外更新** ：防止自动更新引入与当前部署或操作实践不兼容的变更。
### 名称覆盖
在 Kubernetes 集群中部署同一 Helm Chart 的多个实例可能导致命名冲突。使用 `nameOverride` 和 `fullnameOverride` 可区分不同实例。例如，若有生产环境和暂存环境，不同名称可避免混淆。
* 使用 `nameOverride` ，StatefulSet 名称将为 `-` 。
* 使用 `fullnameOverride` ，StatefulSet 名称将为 `` 。
```yaml theme={null}
nameOverride: 'automq-prod'
fullnameOverride: 'automq-instance-prod'
```
### Docker 镜像
Bitnami 可指定用于 AutoMQ 部署的 Docker 镜像，默认镜像为 `bitnami/kafka:latest` 。你需要将其修改为 AutoMQ 自定义镜像及特定版本：
```yaml theme={null}
global:
security:
allowInsecureImages: true
image:
registry: automqinc
repository: automq
tag: 1.5.5-bitnami
pullPolicy: Always
```
### 调度策略
通过节点亲和性（nodeAffinities）和容忍度（tolerations）可为 AutoMQ 在 Kubernetes 中实现细粒度调度策略，我们推荐生产级别的AutoMQ是独占的、非混部的。建议根据节点类型自定义标签匹配规则：
#### 容忍度
建议为 Kubernetes 节点组添加污点 `key: "dedicated", operator: "Equal", value: "automq", effect: "NoSchedule"` 。
```yaml theme={null}
controller:
tolerations:
- key: "dedicated"
operator: "Equal"
value: "automq"
effect: "NoSchedule"
broker:
tolerations:
- key: "dedicated"
operator: "Equal"
value: "automq"
effect: "NoSchedule"
```
#### Node亲和性
覆盖 controller/broker 配置中的默认值以匹配节点标签（如 `node-type: m7g.xlarge` ）：
```yaml theme={null}
controller:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: "node-type"
operator: In
values: ["m7g.xlarge"]
```
#### Pod反亲和性
确保 controller 组件和 broker 组件不会被调度到同一个节点，使用 `podAntiAffinity` 参数：
```yaml theme={null}
controller:
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app.kubernetes.io/instance
operator: In
values:
- automq
- key: app.kubernetes.io/component
operator: In
values:
- controller-eligible
- broker
topologyKey: kubernetes.io/hostname
```
### 扩缩容
#### Controller
实例数通过 `controller.replicas` 配置，支持水平扩缩容。 集群默认部署 3 个 Controller Pod，用户可自定义 Controller 副本数量。
注意：集群部署完成后，暂不支持调整 Controller 的 Replicas，以免出现预期外的风险。
#### Broker
实例数通过 `broker.replicas` 配置，支持水平扩缩容。
#### AutoScaling（HPA）
默认禁用 HPA。若需启用，可在 broker.autoscaling.hpa 中配置参数：
```yaml theme={null}
broker:
autoscaling:
hpa:
enabled: true # 启用HPA
minReplicas: "1" # 最小副本数
maxReplicas: "3" # 最大副本数
targetCPU: "60" # 目标CPU利用率（%）
targetMemory: "" # 目标内存利用率（%，可选）
```
注意：我们不推荐配置Controller HPA因为Kafka KRaft 模式下的 Controller 依赖 Raft 协议维护元数据一致性，不支持自动化 Raft 成员变更，因此配置Controller HPA可能导致 Quorum 失效或集群不可用。
### 资源配置
AutoMQ 的每个 Pod 推荐运行在 4Core16GB 的资源上。通过以下配置调整资源参数：
```yaml theme={null}
controller:
replicaCount: 3
resources:
requests:
cpu: "3000m"
memory: "12Gi"
limits:
cpu: "4000m"
memory: "16Gi"
heapOpts: -Xmx6g -Xms6g -XX:MaxDirectMemorySize=6g -XX:MetaspaceSize=96m
```
```yaml theme={null}
broker:
replicaCount: 2
resources:
requests:
cpu: "3000m"
memory: "12Gi"
limits:
cpu: "4000m"
memory: "16Gi"
heapOpts: -Xmx6g -Xms6g -XX:MaxDirectMemorySize=6g -XX:MetaspaceSize=96m
```
### 安全与认证
可针对 Kafka 中配置的每个监听器设置不同的认证协议。例如，可对客户端通信使用 `sasl_tls` 认证，对 Controller 和 Broker 间通信使用 `tls` 认证。下表列出了可用协议及其提供的安全特性（详情参见 [Kafka 安全认证](https://github.com/bitnami/charts/blob/main/bitnami/kafka/README.md#enable-security-for-kafka)）：
| 方式
| 认证方式
| 通过 TLS 加密
|
| --------------- | ---------------- | --------------- |
| plaintext
| 无
| 否
|
| tls
| 无
| 是
|
| mtls
| 是（双向认证）
| 是
|
| sasl
| 是（通过 SASL）
| 否
|
| sasl\_tls
| 是（通过 SASL）
| 是
|
### 外部访问
需配置额外的监听器和通告监听器，并为每个 Kafka Pod 创建特定服务。
有三种配置外部访问的方式：使用 LoadBalancer 服务、NodePort 服务或 ClusterIP 服务。 具体可以参考 [Kafka 外网访问](https://github.com/bitnami/charts/blob/main/bitnami/kafka/README.md#accessing-kafka-brokers-from-outside-the-cluster) 章节的介绍。
### **监控**
主要涉及到该 Chart 与 Prometheus 的集成。具体可以参考 [开启 Prometheus Metrics](https://github.com/bitnami/charts/tree/main/bitnami/kafka#prometheus-metrics) 章节。
### Table Topic 功能
Table Topic 功能支持 Topic 流式数据与静态数据湖的无缝集成。在 AutoMQ 集群中开启 Table Topic 的功能请参见 [概述▸](/zh/automq/table-topic/overview) 。