Kubernetes 部署多节点集群

本主题介绍如何基于 Kubernetes 部署多节点的 AutoMQ 集群，用户可在该开发环境中验证例如分区迁移、数据自动均衡等集群相关的功能特性。除了 Kubernetes 部署方案，用户可参考以下文档体验其他部署方案：

Linux 主机部署多节点集群▸

面向生产环境负载的 AutoMQ 部署和参数调优相对复杂，您可以通过此处表单联系 AutoMQ 团队获取必要的协助和最佳实践。

此外，如果您期望完全避免安装部署的工作负担，可以通过以下链接体验 AutoMQ 团队提供的全托管云服务，当前各云市场均提供了免费 2 周的试用体验。

前提条件

本文档示例用于部署一个 5 节点的 AutoMQ 集群，其中 3 个节点运行 Controller 和 Broker，剩余 2 个节点仅运行 Broker。需要提前检查如下条件：

准备好一个Kubernetes集群，确保至少有5个 Node ，推荐 4 核 16GB 内存的网络优化型虚拟机，后续在上面进行 Pod 创建等。
Helm chart 确保版本在v3.8.0及以上。参考 Helm Chart 快速入门。
使用Bitnami Helm仓库。AutoMQ 完全兼容 Bitnami 的 Helm Charts，因此您可以基于 Bitnami 的相关 values.yaml 自定义 AutoMQ Kubernetes 集群。
准备2个对象存储的 Bucket，一个用于存储消息数据，一个用于存储系统日志和 Metric 数据。

部署 AutoMQ 集群

第 1 步：编辑配置文件

创建空的 automq-values.yaml 文件，编辑文件并添加特定参数。您可以参考 demo-values.yaml及其子目录下不同场景的推荐配置样例，更多细节参考 README.md。

需要将 ${ops-bucket} 、 ${data-bucket} 、 ${region} 、 ${endpoint} 替换成对象存储的具体值，详情参见对象存储配置▸ 。
将 ${access-key} 和 ${secret-key} 替换成实际的值。你也可以选择 IAM Role 等其他授权方式。
推荐生产级别的 AutoMQ 独占节点部署（避免和其他 Pod 争抢网络带宽等资源），建议通过节点亲和性（nodeAffinity）和容忍度（tolerations）的标签进行匹配。
多可用区部署，可使用 topologySpreadConstraints 参数确保 Pod 在指定可用区间均匀分布。

controller:
  topologySpreadConstraints:
    - maxSkew: 1             
      topologyKey: "topology.kubernetes.io/zone"
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app: automq

避免跨可用区流量， brokerRackAssignment 最终会设置 AutoMQ Broker 的 broker.rack ，客户端配合做设置客户端配置▸，最终达到消除跨可用区流量费用的效果。如在 AWS EKS 可作如下设置：


brokerRackAssignment: aws-az

其他的一些服务端参数可在 controller.extraConfig 和 broker.extraConfig 按需设置。详情请参见： Broker 和 Controller 配置▸ 。

第 2 步：安装AutoMQ

使用自定义 YAML 文件安装或升级 AutoMQ Helm Chart：建议安装 AutoMQ 时使用 --version 指定 31.x.x（31.1.0 ～ 31.5.0）版本的 Bitnami Helm Chart。

helm install automq-release oci://registry-1.docker.io/bitnamicharts/kafka -f demo-values.yaml --version 31.5.0 --namespace automq --create-namespace

等待 AutoMQ 集群就绪：


kubectl --namespace automq rollout status statefulset --watch

当 AutoMQ 集群就绪时，输出应类似以下内容：

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列表：

~/.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 集群。


helm uninstall automq-release -n automq

若历史数据不再需要，需将集群的 PVC、Bucket 数据一并删除，防止脏数据影响下一次部署。

生产环境注意事项

固定 Chart 版本

为避免部署意外变更，建议固定 Helm Chart 版本。固定版本指在部署时指定确切版本，而非使用最新或未指定版本。固定 Helm Chart 版本有助于：

确保兼容性 ：确保部署的应用行为与测试一致，不受新 Chart 版本发布的影响。
避免意外更新 ：防止自动更新引入与当前部署或操作实践不兼容的变更。

名称覆盖

在 Kubernetes 集群中部署同一 Helm Chart 的多个实例可能导致命名冲突。使用 nameOverride 和 fullnameOverride 可区分不同实例。例如，若有生产环境和暂存环境，不同名称可避免混淆。

使用 nameOverride ，StatefulSet 名称将为 <release-name>-<nameOverrride> 。
使用 fullnameOverride ，StatefulSet 名称将为 <fullnameOverride> 。

nameOverride: 'automq-prod'
fullnameOverride: 'automq-instance-prod'

Docker 镜像

Bitnami 可指定用于 AutoMQ 部署的 Docker 镜像，默认镜像为 bitnami/kafka:latest 。你需要将其修改为 AutoMQ 自定义镜像及特定版本：

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" 。

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 ）：

controller:  
  affinity:
    nodeAffinity:  
      requiredDuringSchedulingIgnoredDuringExecution:  
        nodeSelectorTerms:  
        - matchExpressions:  
          - key: "node-type"  
            operator: In  
            values: ["m7g.xlarge"]  

Pod反亲和性

确保 controller 组件和 broker 组件不会被调度到同一个节点，使用 podAntiAffinity 参数：

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 中配置参数：

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 的资源上。通过以下配置调整资源参数：

controller:
  replicaCount: 3
  resources:
    requests:
      cpu: "3000m"
      memory: "12Gi"
    limits:
      cpu: "4000m"
      memory: "16Gi"
  heapOpts: -Xmx6g -Xms6g -XX:MaxDirectMemorySize=6g -XX:MetaspaceSize=96m

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 安全认证）：

方式	认证方式	通过 TLS 加密
plaintext	无	否
tls	无	是
mtls	是（双向认证）	是
sasl	是（通过 SASL）	否
sasl_tls	是（通过 SASL）	是

外部访问

需配置额外的监听器和通告监听器，并为每个 Kafka Pod 创建特定服务。有三种配置外部访问的方式：使用 LoadBalancer 服务、NodePort 服务或 ClusterIP 服务。具体可以参考 Kafka 外网访问章节的介绍。

监控

主要涉及到该 Chart 与 Prometheus 的集成。具体可以参考开启 Prometheus Metrics 章节。

Table Topic 功能

Table Topic 功能支持 Topic 流式数据与静态数据湖的无缝集成。在 AutoMQ 集群中开启 Table Topic 的功能请参见概述▸ 。

关于 AutoMQ

快速开始

部署

迁移

可观测

技术架构

Table Topic

消除跨可用区数据传输

生态集成

配置

版本

测试报告

引用

前提条件

部署 AutoMQ 集群

第 1 步：编辑配置文件

第 2 步：安装AutoMQ

测试消息收发

停止并卸载 AutoMQ 集群

生产环境注意事项

固定 Chart 版本

名称覆盖

Docker 镜像

调度策略

容忍度

Node亲和性

Pod反亲和性

扩缩容

Controller

Broker

AutoScaling（HPA）

资源配置

安全与认证

外部访问

监控

Table Topic 功能

关于 AutoMQ

快速开始

部署

迁移

可观测

技术架构

Table Topic

消除跨可用区数据传输

生态集成

配置

版本

测试报告

引用

​前提条件

​部署 AutoMQ 集群

​第 1 步：编辑配置文件

​第 2 步：安装AutoMQ

​测试消息收发

​停止并卸载 AutoMQ 集群

​生产环境注意事项

​固定 Chart 版本

​名称覆盖

​Docker 镜像

​调度策略

​容忍度

​Node亲和性

​Pod反亲和性

​扩缩容

​Controller

​Broker

​AutoScaling（HPA）

​资源配置

​安全与认证

​外部访问

​监控

​Table Topic 功能

前提条件

部署 AutoMQ 集群

第 1 步：编辑配置文件

第 2 步：安装AutoMQ

测试消息收发

停止并卸载 AutoMQ 集群

生产环境注意事项

固定 Chart 版本

名称覆盖

Docker 镜像

调度策略

容忍度

Node亲和性

Pod反亲和性

扩缩容

Controller

Broker

AutoScaling（HPA）

资源配置

安全与认证

外部访问

监控

Table Topic 功能