Deploy to AWS EKS

Refer to Overview▸, AutoMQ supports deployment on Kubernetes. This article outlines the installation process for deploying AutoMQ on the AWS EKS platform.

​

Prepare EKS Cluster and Compute Resources

If you expect to run the AutoMQ cluster on Kubernetes, you need to prepare an EKS cluster for AutoMQ to use. If you expect to deploy the AutoMQ cluster on EC2, you do not need to prepare an EKS cluster.

​

Step 1: Create the Required IAM Roles

Before creating the EKS cluster and compute resources, create a dedicated IAM Role. This Role is used for the EKS cluster’s own service authorization.

1. Access the IAM console and click Create Role.
2. Trusted entity type: Select AWS Service.
3. Service Use case: Select EKS-Cluster.
4. Click Next, enter a custom role name, and create the IAM Role.

If you use EKS managed node groups, also follow Amazon EKS node IAM role to create the node group IAM Role. If you use Karpenter, prepare the node role referenced by the EC2NodeClass.

​

Step 2: Create EKS Cluster

1. Log in to the AWS EKS console, click Create cluster, and select the custom creation mode.
2. Configure basic cluster information:
   • Bind the EKS cluster IAM Role created in the previous step.
   • Select an EKS-supported Kubernetes version that meets the AutoMQ release requirements.
3. Configure VPC network:
   • Select the VPC you have prepared for AutoMQ; this VPC should be consistent with the VPC where the application is located.
   • Select the private subnets for deploying the cluster.
   • It is recommended to select the default security group for the VPC.
4. Keep other default configurations and create the EKS cluster.
5. Authorize console access. To allow AutoMQ Console to manage the EKS cluster, authorize the IAM Role used by the console.
   1. Go to the Access menu of the EKS cluster and click Create Access Entry.
   2. Select the IAM Role used by AutoMQ Console.
   3. Set Type to Standard.
   4. Click Next, and on the Add access policy page, select the AmazonEKSClusterAdminPolicy policy.
   5. Select Cluster for the Scope and click Add.
   6. Complete the creation.
6. Set security group rules to allow access to Pods and the EKS API Server service from outside the EKS cluster.
   AutoMQ Console needs to call the EKS cluster API Server, so ensure that the network where the console runs can access the API Server on port 443. In addition, AutoMQ Brokers expose service ports. If components outside the cluster, including AutoMQ Console and Producer/Consumer applications, need to access AutoMQ, add inbound rules to the EKS cluster security group.

   • Ports: 443, 9090, 9092, 9102, 9122, 9112, 8083.
   • Source: Set the CIDR ranges or security groups according to where AutoMQ Console and your applications run.

​

Step 3: Prepare EKS Compute Capacity

Prepare stable capacity for Kubernetes system components and dedicated capacity for AutoMQ workloads. Dedicated AutoMQ capacity can use EKS managed node groups or Karpenter.

​

1. Create a System Node Group

1. Go to the EKS cluster details page, click the Compute menu, and Create node group.
2. IAM Role: Select the node group IAM Role you created in Step 1.
3. Instance Configuration: Select t3.medium or equivalent instances, with a recommended quantity of 2-3.
4. Subnet: Select all private subnets required for EKS deployment.
5. Complete the node group creation.

​

2. Prepare Dedicated AutoMQ Capacity

Choose one of the following capacity types. EKS managed node group

1. Go to the Compute menu and Create node group.
2. IAM Role: Select the node group IAM Role created in Step 1.
3. Custom label: Add node-type=automq.
4. Taints: Add key dedicated, value automq, and effect NO_SCHEDULE.
5. Instance Configuration: Select an instance type supported by AutoMQ Console.
6. Subnet: Select private subnets in the one or three Availability Zones planned for the AutoMQ instance.
7. Scaling Configuration: Set a maximum size that can satisfy the planned AutoMQ node count. A starting desired size of 3 nodes is recommended.
8. Complete the node group creation.

Karpenter NodePool

1. Add the custom label node-type=automq and taint dedicated=automq:NoSchedule under spec.template.
2. Ensure that spec.template.spec.requirements permits the instance types and Availability Zones selected in AutoMQ Console.
3. Set CPU and memory limits that can satisfy the planned AutoMQ node count.

For Karpenter installation and EC2NodeClass configuration, see the Karpenter getting started guide. Managed node groups and Karpenter NodePools use the same SchedulingSpec.

​

3. Prepare Kafka Connector Capacity (Optional)

If you plan to use the managed Kafka Connect service provided by AutoMQ, prepare node resources for Connector. Create a separate node pool by referring to the system node group steps, or scale up the system node group to ensure sufficient compute resources.

​

Step 4: Initialize Local Tools and Configure EKS Plugins

The newly created EKS cluster needs to have some necessary system plugins installed to work with AutoMQ.

​

1. Initialize Local Tools

1. Install and configure AWS CLI, kubectl, and Helm in your local environment.
2. Execute the following command to generate the KubeConfig configuration file so that kubectl can connect to your EKS cluster.
   # Replace <region> and <cluster-name> with your actual values
   aws eks update-kubeconfig --region <region> --name <cluster-name>
   

​

2. Configure Cluster Autoscaler for managed node groups (optional)

Use Cluster Autoscaler when EKS managed node groups need to scale on demand. Skip this step when you use Karpenter, which provisions nodes through its own controllers.

1. Download the AutoScaler configuration file from the download link.
2. Modify the configuration file, replacing <YOUR CLUSTER NAME> with your EKS cluster name.
3. Execute the installation command:
   kubectl apply -f cluster-autoscaler-autodiscover.yaml
   

​

3. Prepare IAM authorization for EKS add-ons

The Amazon EBS CSI Driver and AWS Load Balancer Controller need IAM permissions to operate AWS resources. The example commands below use IRSA and eksctl, so create an IAM OIDC provider for the EKS cluster first. For details, see the AWS documentation Create an IAM OIDC provider for your cluster. This OIDC provider is used by the EKS add-ons in the following steps. AutoMQ workload Pods can use either EKS Pod Identity or IRSA. Prepare that workload IAM Role and ServiceAccount in Step 5.

​

4. Configure Amazon EBS CSI Driver

The EKS cluster needs this plugin to manage storage volumes.

1. Refer to the official AWS documentation “Amazon EBS CSI driver” to create a dedicated IAM Role for the CSI Driver after creating the OIDC Provider above.
2. After completing the IAM Role and Trust Policy configuration, go to the Add-ons tab of the EKS cluster console, add the Amazon EBS CSI Driver, and select the IAM Role created in the previous step.

​

5. Install AWS Load Balancer Controller

This plugin is used to manage Load Balancers and provide an external access entry for AutoMQ to the EKS cluster. To install the Load Balancer Controller, you can refer to the official documentation.

1. Execute the following command to generate the IAM Policy.
   curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.10.0/docs/install/iam_policy.json
   aws iam create-policy --policy-name AWSLoadBalancerControllerIAMPolicy --policy-document file://iam-policy.json
   
2. Create an IAM Role and attach the Policy created in the previous step to this Role.
   eksctl create iamserviceaccount \
     --cluster=<cluster-name> \
     --namespace=kube-system \
     --name=aws-load-balancer-controller \
     --attach-policy-arn=arn:aws:iam::<AWS_ACCOUNT_ID>:policy/AWSLoadBalancerControllerIAMPolicy \
     --override-existing-serviceaccounts \
     --region <region-code> \
     --approve
   
3. Add the Helm repository and install the CRD:
   helm repo add eks https://aws.github.io/eks-charts
   kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller/crds?ref=master"
   
4. Execute the installation command, paying attention to replace <eks-cluster-id> with your cluster name, <Your RegionID> with your region ID, and <Your VPCID> with your VPC ID:
   helm upgrade -i aws-load-balancer-controller eks/aws-load-balancer-controller -n kube-system --set clusterName=<eks-cluster-id> --set region=<Your RegionID> --set vpcId=<Your VPCID>
   

​

Step 5: Prepare the AutoMQ Workload IAM Role and ServiceAccount

AutoMQ data plane Pods need AWS permissions to access cloud resources such as S3. Before you create an AutoMQ instance, prepare an IAM Role and a Kubernetes ServiceAccount for the AutoMQ workload. You can bind the ServiceAccount to the IAM Role in either of these ways:

​

Install the Environment Console

After preparing the EKS cluster and compute resources, choose either Deploy AutoMQ Console on EC2▸ or Deploy AutoMQ Console on EKS▸ based on your operational requirements. The console deployment mode does not restrict running the AutoMQ data plane on EKS.

​

Create an AutoMQ instance on Kubernetes

Sign in to AutoMQ Console, create an instance, and configure these fields:

1. Deployment type: Select Kubernetes.
2. VPC and Availability Zones: Select the VPC used by EKS and either one or three workload Availability Zones.
3. Kubernetes cluster: Select the EKS cluster.
4. Load balancer subnets: Select NLB subnets that cover the workload Availability Zones.
5. Instance type: Select a type permitted by the managed node group or Karpenter NodePool.
6. Scheduling YAML: If the dedicated compute pool has labels or taints, enter the corresponding SchedulingSpec.
7. Preview the configuration and create the instance.

AutoMQ adds the selected instance type and Availability Zones to the effective Kubernetes scheduling conditions. Don’t repeat those two conditions in the Scheduling YAML.

​

Appendix: Configure EKS Pod Identity for AutoMQ workloads

For the complete AWS procedure, see Learn how EKS Pod Identity grants pods access to AWS services. Before you start, make sure the EKS Pod Identity Agent is installed in the cluster. You do not need this step if EKS Auto Mode is enabled. The IAM Role must belong to the same AWS account as the EKS cluster for a direct Pod Identity association. Also make sure the AWS principal that creates the association has iam:PassRole permission for the IAM Role.

1. Create an IAM Role and attach the IAM permission policy required by AutoMQ.
2. Configure the role trust policy for EKS Pod Identity:
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
         "Effect": "Allow",
         "Principal": {
           "Service": "pods.eks.amazonaws.com"
         },
         "Action": [
           "sts:AssumeRole",
           "sts:TagSession"
         ],
         "Condition": {
           "StringEquals": {
             "aws:RequestTag/kubernetes-namespace": "<automq-namespace>",
             "aws:RequestTag/kubernetes-service-account": "<automq-service-account>"
           }
         }
       }
     ]
   }
   
3. Create the namespace and ServiceAccount:
   kubectl create namespace <automq-namespace>
   kubectl create serviceaccount <automq-service-account> -n <automq-namespace>
   
4. Create the Pod Identity association:
   aws eks create-pod-identity-association \
     --cluster-name <cluster-name> \
     --namespace <automq-namespace> \
     --service-account <automq-service-account> \
     --role-arn arn:aws:iam::<aws-account-id>:role/<automq-role-name> \
     --region <region-code>
   
5. Before creating the AutoMQ instance, confirm that the association is active and the ServiceAccount exists in the target namespace.

​

Appendix: Configure IRSA for AutoMQ workloads

For the complete AWS procedure, see IAM roles for service accounts.

1. Create an IAM OIDC provider for the EKS cluster. You only need to do this once for each cluster.
   eksctl utils associate-iam-oidc-provider \
     --cluster <cluster-name> \
     --region <region-code> \
     --approve
   
2. Create an IAM Role and attach the IAM permission policy required by AutoMQ.
3. Configure the role trust policy for IRSA:
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/oidc.eks.<region-code>.amazonaws.com/id/<oidc-provider-id>"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "oidc.eks.<region-code>.amazonaws.com/id/<oidc-provider-id>:aud": "sts.amazonaws.com",
             "oidc.eks.<region-code>.amazonaws.com/id/<oidc-provider-id>:sub": "system:serviceaccount:<automq-namespace>:<automq-service-account>"
           }
         }
       }
     ]
   }
   
4. Create the namespace and ServiceAccount, and annotate the ServiceAccount with the IAM Role ARN:
   kubectl create namespace <automq-namespace>
   kubectl create serviceaccount <automq-service-account> -n <automq-namespace>
   kubectl annotate serviceaccount <automq-service-account> \
     -n <automq-namespace> \
     eks.amazonaws.com/role-arn=arn:aws:iam::<aws-account-id>:role/<automq-role-name>
   
5. Before creating the AutoMQ instance, confirm that the annotated ServiceAccount exists in the target namespace.