This document details the process for deploying AutoMQ Enterprise Edition software within an enterprise’s private data center Kubernetes environment utilizing a Helm Chart. For those wishing to deploy AutoMQ in a public cloud environment, it’s recommended to use the AutoMQ Cloud fully managed service directly. Overview▸

​
Prerequisites

Before installing AutoMQ with a Helm Chart, ensure the following prerequisites are satisfied:
  1. Prepare a Kubernetes Environment: Establish an available Kubernetes cluster in advance, ensuring it meets the conditions below:
    1. Allocate Resources for AutoMQ: It is recommended to allocate 4 cores and 16GB of memory for each AutoMQ Pod. Deploying on a dedicated Node is advisable for stable network throughput performance.
    2. Storage Plugin: If your Kubernetes is provided by a cloud vendor, it is advisable to install the storage plugin offered by the vendor to manage EBS volume resources effectively.
  2. Prepare Object Storage Buckets: Each AutoMQ cluster requires two separate object storage buckets: one Ops Bucket for system logs and metrics data, and one Data Bucket for message data. Please refer to the object storage product documentation for guidance on creating them.
  3. Install the Helm Chart Tool: It is recommended to install version 3.6 or higher. You can refer to the documentation for detailed instructions.

​
Obtain the Enterprise Edition Chart.

The AutoMQ Enterprise Edition Chart image is published and made available to the public through an Azure Container Registry (East US). You can test the pull with the following command. 
helm pull oci://automq.azurecr.io/helm/automq-enterprise --version 5.2.0

​
Install AutoMQ

AutoMQ Enterprise Edition offers two types of WAL storage options: EBSWAL and S3WAL. A comparison of the two storage engines is as follows; it is recommended to choose based on your needs. For detailed principles, please refer to the Technical Architecture.
  • EBSWAL Mode: WAL storage uses high-speed EBS volumes, providing <10 ms of send RT performance, currently supported only in public cloud environments like AWS, GCP, and Azure. When using, you need to assign EBS volumes to AutoMQ’s Pods via a StorageClass.
  • S3WAL Mode: Deployment is relatively simple, as WAL storage writes directly to object storage, offering sub-100 ms send RT performance. It supports all public cloud environments as well as private data centers (as long as they provide S3-compatible object storage). Deployment is relatively straightforward, with no need to allocate EBS volumes.
The following section provides a configuration file example, with the default mode set to S3WAL. If you wish to configure EBSWAL, please modify these configuration parameters accordingly.

​
Step 1: Create Credentials and Perform Authorization.

AutoMQ clusters require access to external services such as object storage and storage volumes. Therefore, before installation, you need to create credentials for AutoMQ and complete the authorization process.
If AutoMQ is deployed in the AWS public cloud environment using AWS S3 storage, you must access the IAM product to create an authorization policy. AutoMQ must be granted permission for the following operations to access AWS S3:
- actions:
    - s3:GetLifecycleConfiguration
    - s3:PutLifecycleConfiguration
    - s3:ListBucket
    - s3:PutObject
    - s3:GetObject
    - s3:AbortMultipartUpload
    - s3:PutObjectTagging
    - s3:DeleteObject
If you deploy using the EBSWAL mode, additional authorization for the following policy is required:
- actions:
    - ec2:DescribeVolumes
    - ec2:DetachVolume
    - ec2:DescribeAvailabilityZones
After creating an IAM authorization policy, credentials can be generated using two methods.
  • Using IAM Subaccount Static AccessKey: In this approach, attach the authorization policy to the IAM subaccount and utilize the subaccount’s static AccessKeyId and AccessKeySecret as credentials to access AutoMQ.
  • Using IAM Role Dynamic Credentials: For this approach, create an IAM Role and attach the authorization policy to the Role. Dynamic credentials allow access to AutoMQ through a Pod assuming the EC2 Role in EKS.
To clarify illustrations, the following configuration file example employs a static AccessKey as credentials.

​
Step 2: Create Storage Class

Before installing AutoMQ, you must declare a Storage Class in the Kubernetes cluster for allocating storage volumes. These storage volumes serve several purposes:
  • Storing AutoMQ Controller Metadata: In the AutoMQ cluster, the Controller Pod responsible for metadata management must mount the storage volumes to store KRaft metadata.
  • EBSWAL Mode Storage for WAL Data (Optional): If you plan to deploy using the EBSWAL mode, each Broker Pod will also require a mounted data volume for writing WAL data.
Please specify the Storage Class based on the Kubernetes storage plugin from your cloud provider or private data center, then keep a record of the Storage Class name for later parameter configuration.
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

​
Step 3: Initialize the Configuration File

The configuration information for the AutoMQ Enterprise Edition Chart is composed of multiple parts, allowing for user customization via the values.yaml file. First, create an empty file named automq-values.yaml. Edit this file to add specific parameters. You can refer to the demo-values.yaml for recommended configuration samples in the directory, and for more details, consult README.md.
Note:The following configuration items are based on the S3WAL mode; parameter values are filled using placeholders. Before installation, these values need to be set based on the actual situation. You may also adjust them for the EBS WAL mode as per the parameter documentation.
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"
In the configuration file generated in the previous step, certain parameters must be updated according to your actual conditions.

​
Modify Common Parameters.

global.cloudProvider.name This parameter specifies the deployment cloud environment. Please insert the enumerated value according to the name of the cloud provider. If it is a private data center, you’ll also need to fill it in with the enumerated value.
Deployment Environment
Parameter Enumerated Value
AWS
aws
Google Cloud
gcp
Azure
azure
Alibaba Cloud
aliyun
global.cloudProvider.credentials This parameter details the public credentials used by the AutoMQ cluster to access cloud resources. The current example utilizes static credentials of the AccessKey type. To use the IAM Role method, please refer to the advanced parameter documentation for guidance on modifications. 
global:
  cloudProvider: 
    credentials: static://?accessKey=<your-accesskey>&secretKey=<your-secretkey>
KAFKA_S3_ACCESS_KEY and KAFKA_S3_SECRET_KEY Environment Variables The example configuration file employs static credentials of the AccessKey type. Therefore, in addition to the global.cloudProvider.credentials parameter, you need to update the Controller and Broker environment variables with the correct credentials. Refer to the credentials created in Step 1 to update the credentials in the example: 
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 This parameter specifies the configuration for accessing object storage using S3URL, which includes three components: s3.ops.buckets, s3.data.buckets, and s3.wal.path.
Below is an example configuration using the S3WAL mode with static credentials. If you need to use EBSWAL mode, please refer to the advanced configuration section for modification instructions.
Fill in the Ops Bucket and Data Bucket created in the prerequisites according to your actual scenario.
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

​
Adjust Parameters like the Storage Class.

controller.persistence.metadata.storageClass Substitute this parameter with the name of the Storage Class created in step 2, which is designated for storing metadata in the AutoMQ Controller Pod.

​
Revise the Cluster Topology and Resource Request Parameters.

Adjust the cluster topology and resource request parameters based on the resources allocated to AutoMQ Node. The parameters that need modification are as follows: broker.replicas The AutoMQ Enterprise Chart will start with three Controller Pods by default. These Controller Pods also provide data read and write capabilities. If users wish to horizontally scale more Brokers, they can set the broker.replicas parameter.
  • Default value: 0, which represents a three-node cluster without the need for additional Brokers.
  • Setting range: >= 0, configured as needed.
Resource Request Parameters AutoMQ Enterprise Edition Controller and Broker Pods need to have the Request and Limit parameters adjusted, along with the corresponding JVM HEAP settings. The configuration files mentioned earlier default to a 4Core16GB specification. Please update these parameters based on the actual allocated computing resources.
  • 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]

​
Step 4: Install Chart and Access the Cluster

After customizing the values.yaml configuration file to suit your deployment requirements, proceed with the installation of 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
Once the installation is complete, users can access AutoMQ within the Kubernetes cluster, either through a Headless service or a LoadBalancer.
Note: We recommend deploying an Internal LoadBalancer to prevent changes in Pod IP addresses.

​
Step 5: Connect and Test the Cluster

​
Headless Service

  1. Locate the Headless service

kubectl get svc --namespace <namespace> -l "app.kubernetes.io/component=controller" -w
  1. Connecting and Testing Using Kafka Clients
Use the Headless Service for your Kafka client’s --bootstrap-server option to send and receive messages. Here’s the command you can use: 

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

  1. Find External Address
Wait for the EXTERNAL-IP to be assigned. Use the following command: 

kubectl get svc --namespace <namespace> -l "app.kubernetes.io/component=controller" -w
You can obtain the external IP of the LoadBalancer.
  1. Connect and Test Using Kafka Clients
Port 9092 is used for client access. 

# Replace <EXTERNAL-IP> with the Address from the Previous Step
./kafka-console-producer.sh \
  --bootstrap-server <EXTERNAL-IP>:9092 \
  --topic test-topic

​
Other Advanced Configurations

The deployment document above provides a basic example of deploying AutoMQ in S3WAL mode. In real-world production environments, users can choose more advanced configurations like EBSWAL and integrate Auto-Scaler support. For the full configuration file, refer to Helm Chart Values Readme▸.

​
Configuring the WAL Type

In the previously mentioned installation steps, S3WAL was used as an example. AutoMQ supports deployment options for both EBSWAL and S3WAL modes.
In S3WAL mode, there’s no need to mount a WAL data volume, making the configuration relatively straightforward. First, configure the global.config.s3.wal.path parameter.

config: |  
  s3.wal.path=0@s3://<xxx-data-bucket>?region=<region>&endpoint=<endpoint>&authType=<authType>
Then, disable controller.persistence.wal.enabled and broker.persistence.wal.enabled.
# Applying StorageClass in Controller/broker
controller:  
  persistence:  
    metadata:  
      storageClass: "your-storage-class"  
    wal:
      enabled: false
broker:  
  persistence:
    wal:
      enabled: false

​
Setting Credentials

AutoMQ supports accessing external resources using either static AccessKeys or dynamic IAM Roles. To prevent the leakage of static AccessKey configurations in production environments, it is recommended to use dynamically generated credentials provided by the cloud provider’s IAM Roles.
When using IAM Role Credentials, it is necessary to attach the authorization policy to the Role in Step 1. Then, refer to the example below to modify the Credentials configuration.
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>
The format for filling out credentials parameters is outlined in the following table:**
Deployment EnvironmentParameter Values
AWS
instance://?role=<your-instance-profile>
For Role, enter the IAM instance profile, not the Role ARN.
Google Cloud
instance://?role=<your-service-account-name>
For Role, enter the name of the GCP ServiceAccount.
Azure
instance://?role=<your-managed-identity-client-id>
For Role, enter the Azure Managed Identity Client ID.
Alibaba Cloud
instance://?role=<your-role-id>
For Role, enter the RAM Role name of Alibaba Cloud.

​
Set Fine-grained Scheduling Policies

In Kubernetes, AutoMQ’s fine-grained scheduling policy is implemented using node affinities and tolerations. Users are advised to customize label matching rules based on their node types:

​
Tolerations

It’s recommended to add a taint to the Kubernetes node group with the key “dedicated,” operator “Equal,” value “automq,” and effect “NoSchedule.” Then, configure the corresponding toleration rules in global.tolerations to schedule Pods: 
global:  
  tolerations:  
  - key: "dedicated"  
    operator: "Equal"  
    value: "automq"  
    effect: "NoSchedule"

​
Node Affinities

Override default values in the controller/agent configuration to align with node labels (e.g., node-type: automq-worker): 
controller:  
  nodeAffinity:  
    requiredDuringSchedulingIgnoredDuringExecution:  
      nodeSelectorTerms:  
      - matchExpressions:  
        - key: "node-type"  
          operator: In  
          values: ["automq-worker"]

​
Set up Auto-scaling

​
Number of Controllers

By default, the cluster deploys 3 Controller Pods, but users can customize the number of Controller replicas.
Note: Once the cluster is deployed, adjusting the number of Controller replicas is not supported to avoid unforeseen risks.

​
Number of Brokers

The number of brokers is managed by the broker.replicas parameter, which allows for horizontal scaling. By default, there are 0 brokers.

​
Auto-scaling Configuration

By default, HPA (Horizontal Pod Autoscaler) is disabled. To activate it, two conditions must be fulfilled:
  • broker.replicas > 0
  • Enable and configure parameters in 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)

​
Identity Recognition Configuration

AutoMQ allows overriding of protocol listeners and enabling secure authentication. By default, it uses the following ports:
  • Client to server access: 9092 (PLAINTEXT).
  • Internal communication between Controllers: 9093 (PLAINTEXT).
  • Internal communication between Brokers: 9094 (PLAINTEXT).
AutoMQ also enables secure authentication by configuring listener overrides (e.g., enabling SASL authentication) for custom ports and protocols. Allowed values include ‘PLAINTEXT’, ‘SASL_PLAINTEXT’, ‘SASL_SSL’, and ‘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: ""
Additionally, you can set a password for it, which is randomly generated by default.
sasl:
  controller:
    user: "user1"
    password: "PWDxxx"
  interbroker:
    user: "user2"
    password: "PWDxxx"
  client: 
    user: "user3"
    password: "PWDxxx"