使用 Helm Chart 部署 AutoMQ 企业版

本文档介绍如何在企业私有数据中心的 Kubernetes 环境中使用 Helm Chart 部署 AutoMQ 企业版软件。如果期望在公有云环境使用 AutoMQ，推荐直接使用 AutoMQ Cloud 全托管服务概述▸。

前置条件

使用 Helm Chart 安装 AutoMQ 之前，需要满足如下条件：

准备 Kubernetes 环境 ：提前准备一个可用的 Kubernetes 集群，并满足如下条件：
1. 预留 AutoMQ 计算资源 ：AutoMQ 每个 Pod 推荐分配 4Core16GB 资源，并建议独占 Node 部署以获取稳定的网络吞吐性能。
2. 存储插件： 如果您的 Kubernetes 由云厂商提供，推荐安装云厂商提供的存储插件用于管理 EBS 卷资源。
准备对象存储 Bucket。 AutoMQ 每个集群需要 2 个独立的对象存储 Bucket，一个是 Ops Bucket 用于存储系统日志和 Metrics 数据，一个是 Data Bucket 存储消息数据。请参考对象存储产品的文档创建。
安装 Helm Chart 工具： 推荐安装大于等于 3.6 版本。可参考文档操作。

获取企业版 Chart

AutoMQ 企业版 Chart 镜像通过 Azure Container Registry (East US) 镜像仓库进行发布和公开。您可以通过如下命令进行拉取测试。


helm pull oci://automq.azurecr.io/helm/automq-enterprise --version 5.2.0

安装 AutoMQ

AutoMQ 企业版提供两种 WAL 存储类型，分别是 EBSWAL 和 S3WAL，两种存储引擎对比如下，建议根据需求选择。详细原理请参考技术架构。

EBSWAL 模式： WAL 存储使用高速 EBS 卷，提供 <10 毫秒的发送 RT 性能，目前仅支持 AWS、GCP、Azure 等公有云环境，使用时需要通过 StorageClass，为 AutoMQ 的 Pod 分配 EBS 卷。
S3WAL 模式： 部署相对简单，WAL 存储直接写对象存储，提供百毫秒级的发送 RT 性能，支持所有公有云环境以及私有数据中心（提供兼容 S3 的对象存储即可），部署相对简单，无需分配 EBS 卷。

下方章节提供的配置文件示例，默认使用 S3WAL 模式。如需配置 EBSWAL，请修改配置参数。

Step1：创建 Credentials，并进行授权

AutoMQ 集群需要访问对象存储和存储卷等外部服务，因此在安装前需要为 AutoMQ 创建 Credentials 并完成授权。

AWS 公有云环境部署 AutoMQ 且使用 AWS S3 存储，则需要前往 IAM 产品创建授权策略，AutoMQ 访问 AWS S3 需要被授予以下操作权限：


- actions:
    - s3:GetLifecycleConfiguration
    - s3:PutLifecycleConfiguration
    - s3:ListBucket
    - s3:PutObject
    - s3:GetObject
    - s3:AbortMultipartUpload
    - s3:PutObjectTagging
    - s3:DeleteObject

如果您使用 EBSWAL 模式部署，则需要额外授权如下策略：


- actions:
    - ec2:DescribeVolumes
    - ec2:DetachVolume
    - ec2:DescribeAvailabilityZones

用户创建 IAM 授权策略后，可以通过以下两种方式创建 Credentials。

使用 IAM 子账号静态 AccessKey： 此模式下需要将授权策略附加给 IAM 子账号，并通过 IAM 子账号的静态 AccessKeyId 和 AccessKeySecret 作为 Credentials 访问 AutoMQ。
使用 IAM Role 动态凭证： 此模式下需要创建 IAM Role，需要将授权策略附加给 Role。然后在 EKS 上通过 Pod 扮演 EC2 Role 的动态 Credentials 访问 AutoMQ。

为简化示例，下文的配置文件示例使用静态 AccessKey 作为 Credentials。

Step2：创建 Storage Class

安装 AutoMQ 之前需要在 Kubernetes 集群申明 Storage Class，用于后续分配存储卷。存储卷有以下用途：

存储 AutoMQ Controller 元数据： AutoMQ 集群中用于元数据管理的 Controller Pod 需要挂载存储卷存储 KRaft 元数据。
EBSWAL 模式存储 WAL 数据（可选） ：如果期望部署 EBSWAL 模式，每个 Broker Pod 也需要挂载数据卷用于写入 WAL 数据。

请根据云厂商或者私有数据中心的 Kubernetes 存储插件申明 Storage Class ，然后记录该 Storage Class 名称，用于后续参数配置。


apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: automq-disk-eks-gp3
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3  # EBS volume type
allowVolumeExpansion: true

Step3：初始化配置文件

AutoMQ 企业版 Chart 的配置信息包含多个部分，支持用户通过 values.yaml 文件进行自定义覆盖。首先，需要创建一个空文件 automq-values.yaml 。编辑文件并添加特定参数。您可以参考目录下的 demo-values.yaml推荐配置样例，更多细节参考 README.md。

注意：下方提供的配置项基于 S3WAL 模式， 其中参数值均使用占位符填充，安装前需要根据实际情况填充参数值，也可以根据参数文档修改为 EBS WAL 模式。


global:
  cloudProvider:
    name: "Replace With Your True Cloud Provider Name"
    credentials: "Replace With Your True Your Credentials"
  config: |
    s3.ops.buckets=Replace With Your True Ops Bucket URL
    s3.data.buckets=Replace With Your True Data Bucket URL
    s3.wal.path=Replace With Your True WAL PATH

controller:
  resources:
    requests:
      cpu: "1000m"
      memory: "12Gi"
    limits:
      cpu: "2000m"
      memory: "16Gi"
  persistence:
    metadata:
      storageClass: "Replace With Your True StroageClass"
    wal:
      enabled: false

  annotations:

  env:
    - name: "KAFKA_HEAP_OPTS"
      value: "-Xmx6g -Xms6g -XX:MaxDirectMemorySize=6g -XX:MetaspaceSize=96m"
    - name: "KAFKA_S3_ACCESS_KEY"
      value: "Replace With Your True ACCESS_KEY"
    - name: "KAFKA_S3_SECRET_KEY"
      value: "Replace With Your True SECRET_KEY"

broker:
  replicas: 0
  resources:
    requests:
      cpu: "1000m"
      memory: "12Gi"
    limits:
      cpu: "2000m"
      memory: "16Gi"

  persistence:
    wal:
      enabled: false

  annotations:

  env:
    - name: "KAFKA_HEAP_OPTS"
      value: "-Xmx6g -Xms6g -XX:MaxDirectMemorySize=6g -XX:MetaspaceSize=96m"
    - name: "KAFKA_S3_ACCESS_KEY"
      value: "Replace With Your True ACCESS_KEY"
    - name: "KAFKA_S3_SECRET_KEY"
      value: "Replace With Your True SECRET_KEY"

在上一步生成的配置文件中，部分参数需要根据实际情况进行替换。

修改公共参数

global.cloudProvider.name 该参数约定了部署的云环境，请根据云厂商名称枚举值填写，如果是私有数据中心，也需要按照枚举值填充。

部署环境	参数枚举值
AWS	aws
Google Cloud	gcp
Azure	azure
阿里云	aliyun

global.cloudProvider.credentials 该参数约定了 AutoMQ 集群访问云资源时使用的公共 Credentials 参数。当前示例以 AccessKey 类型的静态 Credentials 为例，如果期望使用 IAM Role 方式请参照高阶参数文档描述修改。


global:
  cloudProvider: 
    credentials: static://?accessKey=<your-accesskey>&secretKey=<your-secretkey>

KAFKA_S3_ACCESS_KEY 和 KAFKA_S3_SECRET_KEY 环境变量 示例的配置文件使用了 AccessKey 类型的静态 Credentials ，因此，除了 global.cloudProvider.credentials 参数，还需要将 Controller、Broker 的环境变量替换为正确的 Credentials。参考 Step1 创建的 Credentials，将示例中的 Credentials 进行替换：


controller:
  env:
    - name: "KAFKA_S3_ACCESS_KEY"
      value: "Replace With Your True ACCESS_KEY"
    - name: "KAFKA_S3_SECRET_KEY"
      value: "Replace With Your True SECRET_KEY"

broker:
  env:
    - name: "KAFKA_S3_ACCESS_KEY"
      value: "Replace With Your True ACCESS_KEY"
    - name: "KAFKA_S3_SECRET_KEY"
      value: "Replace With Your True SECRET_KEY"

global.config 该参数约定了访问对象存储的 S3URL 配置，其中包括三个部分，分别是s3.ops.buckets、s3.data.buckets 以及 s3.wal.path。

下方是使用 S3WAL 模式、静态 Credentials 的示例配置，如果您需要使用 EBSWAL 模式，请参考高阶配置章节的说明进行修改。

根据实际情况填充前置条件中创建的 Ops Bucket 和 Data Bucket。


config: |
  s3.data.buckets=0@s3://<your-data-bucket>?region=xxxx&endpoint=https://s3.xxxx.amazonaws.com&authType=static
  s3.ops.buckets=1@s3://<your-ops-bucket>?region=xxxx&endpoint=https://s3.xxxx.amazonaws.com&authType=static
  s3.wal.path=0@s3://<your-data-bucket>?region=xxxx&endpoint=https://s3.xxxx.amazonaws.com&authType=static

修改存储类等参数

controller.persistence.metadata.storageClass 根据实际情况，将该参数替换成步骤 2 中创建的 Storage Class 名称，用于设置 AutoMQ Controller Pod 存储元数据。

修改集群拓扑和资源 Request 参数

根据实际为 AutoMQ 分配的 Node 资源，调整集群拓扑和资源 Request 参数。需要修改的参数如下： broker.replicas AutoMQ 企业版 Chart 默认会启动三个 Controller Pod，Controller Pod 同时也可以提供数据读写能力，如果用户期望额外水平扩展更多的 Broker，则可以设置 broker.replicas 参数。

默认值：0，代表三节点集群，不需要额外的 Broker。
设置范围：>= 0，按需配置。

资源 Request 参数 AutoMQ 企业版 Controller 和 Broker 的 Pod 需要调整 Request 和 Limit 参数以及相应的 JVM HEAP 参数。上述配置文件中默认按 4Core16GB 规格配置，请根据实际分配的计算资源按需调整以下参数。

controller.resources.requests.cpu
controller.resources.requests.memory
controller.resources.limits.cpu
controller.resources.limits.memory
controller.env.[KAFKA_HEAP_OPTS]
broker.resources.requests.cpu
broker.resources.requests.memory
broker.resources.limits.cpu
broker.resources.limits.memory
broker.env.[KAFKA_HEAP_OPTS]

Step4：安装 Chart 并访问集群

根据实际部署需求调整好 values.yaml 配置文件后，即可安装 AutoMQ。


helm upgrade --install <release-name> oci://automq.azurecr.io/helm/automq-enterprise --version 5.2.0 -f <your-custom-values.yaml> --namespace <namespace> --create-namespace

安装完成后，用户即可在 Kubernetes 集群内访问 AutoMQ，可通过Headless service或者LoadBalancer进行访问

注意：我们推荐部署Internal LoadBalancer防止Pod ip发生变化

Step5: 连接和测试集群

Headless service

查找Headless service


kubectl get svc --namespace <namespace> -l "app.kubernetes.io/component=controller" -w

使用Kafka客户端进行连接和测试

Headless Service用作你的 Kafka 客户端的 --bootstrap-server 进行收发消息，可使用以下命令：


./kafka-console-producer.sh \
  --bootstrap-server <release-name>-automq-enterprise-controller-0.<release-name>-automq-enterprise-controller-headless.<namespace>.svc.cluster.local:9092 \
  --topic test-topic

LoadBalancer

查找 External Address

等待 EXTERNAL-IP（外部 IP）分配完成。使用的命令如下：


kubectl get svc --namespace <namespace> -l "app.kubernetes.io/component=controller" -w

你可以获取到LoadBalancer的external IP

使用Kafka客户端进行连接和测试

Port 9092 被用作client的访问


# Replace <EXTERNAL-IP> with the address from the previous step
./kafka-console-producer.sh \
  --bootstrap-server <EXTERNAL-IP>:9092 \
  --topic test-topic

其他高阶配置

上述部署文档演示了 AutoMQ 使用 S3WAL 模式部署的简单示例，在实际生产场景中用户可以选择 EBSWAL、添加 Auto-Scaler 支持等高阶配置。完整的配置文件参考 Helm Chart Values 文档▸。

设置 WAL 类型

上述安装步骤中使用 S3WAL 作为示例，AutoMQ 同时支持 EBSWAL 和S3WAL两种部署方式。

S3WAL 模式下，无需挂载 WAL 数据卷，配置相对简单，首先配置 global.config.s3.wal.path 参数。


config: |  
  s3.wal.path=0@s3://<xxx-data-bucket>?region=<region>&endpoint=<endpoint>&authType=<authType>

然后关闭 controller.persistence.wal.enabled 和 broker.persistence.wal.enabled 。


# Applying StorageClass in controller/broker  
controller:  
  persistence:  
    metadata:  
      storageClass: "your-storage-class"  
    wal:
      enabled: false
broker:  
  persistence:
    wal:
      enabled: false

设置 Credentials

AutoMQ 同时支持使用静态的 AccessKey 或者动态 IAM Role 访问外部资源。生产环境中为防止静态的 AccessKey 配置泄露，更加推荐使用云厂商提供的 IAM Role 动态 Credentials。

使用 IAM Role Credentials 则需要在 Step1 中将授权策略附加给 Role。然后参考下方示例修改 Credentials 配置。


global:
  cloudProvider: 
    credentials: instance://?role=<your-instance-profile>

  config: |
    s3.data.buckets=0@s3://<your-bucket>?authType=instance&role=<role-id>
    s3.ops.buckets=1@s3://<your-bucket>?authType=instance&role=<role-id>

其中 credentials 的格式填写格式参考如下表格**：**

部署环境	参数枚举值
AWS	instance://?role=<your-instance-profile> Role 填写 IAM 实例配置文件，不是 Role ARN。
Google Cloud	instance://?role=<your-service-account-name> Role 填写 GCP 的 ServiceAccount 名称。
Azure	instance://?role=<your-managed-identity-client-id> Role 填写 Azure 的 Managed Identity Client ID。
阿里云	instance://?role=<your-role-id> Role 填写阿里云的 RAM Role 名称。

设置细粒度调度策略

在 Kubernetes 中，AutoMQ 的细粒度调度策略是通过 nodeAffinities 和 tolerations 实现的。建议用户根据其节点类型自定义标签匹配规则：

Tolerations

建议在 Kubernetes 节点组中添加一个污点，键为：“dedicated”，运算符为：“Equal”，值为：“automq”，效果为：“NoSchedule”。并在 global.tolerations 中配置相应的容忍规则，以调度 Pod：


global:  
  tolerations:  
  - key: "dedicated"  
    operator: "Equal"  
    value: "automq"  
    effect: "NoSchedule"

Node Affinities

覆盖控制器/代理配置中的默认值以匹配节点标签（例如，node-type: automq-worker）：


controller:  
  nodeAffinity:  
    requiredDuringSchedulingIgnoredDuringExecution:  
      nodeSelectorTerms:  
      - matchExpressions:  
        - key: "node-type"  
          operator: In  
          values: ["automq-worker"]

设置弹性伸缩

Controller 数量

集群默认部署 3 个 Controller Pod，用户可自定义 Controller 副本数量。

注意：集群部署完成后，暂不支持调整 Controller 的 Replicas，以免出现预期外的风险。

Broker 数量

Broker 数量通过 broker.replicas 参数控制，可以水平扩展。默认为 0 个。

Auto-scaling 配置

默认情况下，HPA（Horizontal Pod Autoscaler）是禁用的。要启用它，必须满足两个条件：

broker.replicas > 0
在 global.autoscaling.hpa 中启用并配置参数：


global:  
  autoscaling:  
    hpa:  
      enabled: true        # Enable HPA  
      minReplicas: "1"     # Minimum replicas  
      maxReplicas: "3"     # Maximum replicas  
      targetCPU: "60"      # Target CPU utilization (%)  
      targetMemory: ""     # Target memory utilization (%) (optional)

身份识别配置

AutoMQ 支持覆盖协议监听并启用安全认证，默认情况下会暴露以下端口：

客户端访问服务端：9092（PLAINTEXT）。
Controller 间内部通信：9093（PLAINTEXT）。
Broker 间内部通信：9094（PLAINTEXT）。

AutoMQ 还通过监听器配置（例如，启用 SASL 认证）覆盖自定义端口和协议来启用安全认证（允许的值有 ‘PLAINTEXT’、‘SASL_PLAINTEXT’、‘SASL_SSL’ 和 ‘SSL’）。


listeners:  
  client:   
    - containerPort: 9092  
      protocol: SASL_PLAINTEXT  
      name: BROKER_SASL  
      sslClientAuth: ""          # Optional: Configure SSL authentication policy  
  controller:   
    - containerPort: 9093  
      protocol: SASL_PLAINTEXT  
      name: CONTROLLER_SASL  
      sslClientAuth: ""  
  interbroker:   
    - containerPort: 9094  
      protocol: SASL_PLAINTEXT  
      name: BROKER_SASL  
      sslClientAuth: ""

同时你可以为其设置密码，默认随机生成


sasl:
  controller:
    user: "user1"
    password: "PWDxxx"
  interbroker:
    user: "user2"
    password: "PWDxxx"
  client: 
    user: "user3"
    password: "PWDxxx"

产品介绍

快速开始

AutoMQ on Kubernetes 部署

订阅和计费

管理环境

管理账号成员

管理 AutoMQ

迁移到 AutoMQ

安全配置

监控报警

Table Topic

最佳实践

版本记录

服务支持

附录

使用 Helm Chart 部署 AutoMQ 企业版

前置条件

获取企业版 Chart

安装 AutoMQ

Step1：创建 Credentials，并进行授权

Step2：创建 Storage Class

Step3：初始化配置文件

修改公共参数

修改存储类等参数

修改集群拓扑和资源 Request 参数

Step4：安装 Chart 并访问集群

Step5: 连接和测试集群

Headless service

LoadBalancer

其他高阶配置

设置 WAL 类型

设置 Credentials

设置细粒度调度策略

Tolerations

Node Affinities

设置弹性伸缩

Controller 数量

Broker 数量

Auto-scaling 配置

身份识别配置

产品介绍

快速开始

AutoMQ on Kubernetes 部署

订阅和计费

管理环境

管理账号成员

管理 AutoMQ

迁移到 AutoMQ

安全配置

监控报警

Table Topic

最佳实践

版本记录

服务支持

附录

​前置条件

​获取企业版 Chart

​安装 AutoMQ

​Step1：创建 Credentials，并进行授权

​Step2：创建 Storage Class

​Step3：初始化配置文件

​修改公共参数

​修改存储类等参数

​修改集群拓扑和资源 Request 参数

​Step4： 安装 Chart 并访问集群

​Step5: 连接和测试集群

​Headless service

​LoadBalancer

​其他高阶配置

​设置 WAL 类型

​设置 Credentials

​设置细粒度调度策略

​Tolerations

​Node Affinities

​设置弹性伸缩

​Controller 数量

​Broker 数量

​Auto-scaling 配置

​身份识别配置

前置条件

获取企业版 Chart

安装 AutoMQ

Step1：创建 Credentials，并进行授权

Step2：创建 Storage Class

Step3：初始化配置文件

修改公共参数

修改存储类等参数

修改集群拓扑和资源 Request 参数

Step4：安装 Chart 并访问集群

Step5: 连接和测试集群

Headless service

LoadBalancer

其他高阶配置

设置 WAL 类型

设置 Credentials

设置细粒度调度策略

Tolerations

Node Affinities

设置弹性伸缩

Controller 数量

Broker 数量

Auto-scaling 配置

身份识别配置