Kubernetes 部署多节点集群

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

Linux 主机部署多节点集群▸

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

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

前提条件

本文档示例用于部署一个 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 集群

​第 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 功能