> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy to AWS EKS

> AutoMQ offers full Kafka compatibility and a cloud-native architecture based on AWS EKS, providing an efficient and scalable message queue service.

Refer to [Overview▸](/automq-cloud/deploy-automq-on-kubernetes/overview), AutoMQ supports deployment on Kubernetes. This article outlines the installation process for deploying AutoMQ on the AWS EKS platform.

<Info>
  Throughout the product's **full lifecycle**, AutoMQ will maintain deep and continuous integration with Amazon Elastic Kubernetes Service (EKS) and EKS Anywhere (EKS-A).

  To uphold this commitment, we ensure:

  **Continuous version compatibility:** We guarantee that each new version of AutoMQ will be compatible with both current and future versions of EKS and EKS-A. Additionally, we proactively adapt to updates on the AWS platform, offering users a forward-compatible experience.

  **Timely response and resolution:** We have established a clear response mechanism to quickly identify and resolve any configuration, security, and non-security issues reported by customers or AWS.
</Info>

## 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](https://docs.aws.amazon.com/eks/latest/userguide/create-node-role.html) 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](https://console.aws.amazon.com/eks/home), 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.**

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

### 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](https://karpenter.sh/docs/getting-started/getting-started-with-karpenter/). Managed node groups and Karpenter NodePools use the same [SchedulingSpec](/automq-cloud/deploy-automq-on-kubernetes/overview#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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), [kubectl](https://kubernetes.io/docs/tasks/tools/), and [Helm](https://helm.sh/docs/intro/install/) in your local environment.
2. Execute the following command to generate the KubeConfig configuration file so that `kubectl` can connect to your EKS cluster.
   ```bash theme={null}
   # 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](https://download.automq.com/eks-config/cluster-autoscaler-autodiscover.yaml).
2. Modify the configuration file, replacing `<YOUR CLUSTER NAME>` with your EKS cluster name.
3. Execute the installation command:
   ```bash theme={null}
   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](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html).

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](#step-5-prepare-the-automq-workload-iam-role-and-serviceaccount).

#### 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](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html)" 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](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/deploy/installation/#option-b-attach-iam-policies-to-nodes).

1. Execute the following command to generate the IAM Policy.
   ```bash theme={null}
   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.
   ```bash theme={null}
   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:
   ```bash theme={null}
   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:
   ```bash theme={null}
   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:

| Method           | When to use it                                                                                                                                                                                   | Trust policy difference                                                                                              | ServiceAccount binding                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| EKS Pod Identity | Recommended for new EKS clusters when you want EKS to manage the association between the role and the ServiceAccount.                                                                            | The role trusts the AWS service principal `pods.eks.amazonaws.com` and allows `sts:AssumeRole` and `sts:TagSession`. | Create an EKS Pod Identity association between the cluster, namespace, ServiceAccount, and IAM Role. |
| IRSA             | Use this when your cluster already uses IAM roles for service accounts, when you need compatibility with existing IRSA automation, or when Pod Identity is not supported for your workload type. | The role trusts the cluster OIDC provider as a federated principal and allows `sts:AssumeRoleWithWebIdentity`.       | Annotate the Kubernetes ServiceAccount with `eks.amazonaws.com/role-arn=<role-arn>`.                 |

<Tip>
  The IAM permission policy attached to the role can be the same for both methods. The main difference is the IAM Role trust policy and how the ServiceAccount is associated with the role. See [Appendix: Configure EKS Pod Identity for AutoMQ workloads](#appendix-configure-eks-pod-identity-for-automq-workloads) and [Appendix: Configure IRSA for AutoMQ workloads](#appendix-configure-irsa-for-automq-workloads) for the detailed setup.
</Tip>

## Install the Environment Console

After preparing the EKS cluster and compute resources, choose either [Deploy AutoMQ Console on EC2▸](/automq-cloud/getting-started/install-byoc-environment/aws/install-automq-on-aws#deploy-automq-console-on-ec2) or [Deploy AutoMQ Console on EKS▸](/automq-cloud/getting-started/install-byoc-environment/aws/install-automq-on-aws#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](/automq-cloud/deploy-automq-on-kubernetes/overview#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](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).

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:

   ```json theme={null}
   {
     "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:

   ```bash theme={null}
   kubectl create namespace <automq-namespace>
   kubectl create serviceaccount <automq-service-account> -n <automq-namespace>
   ```

4. Create the Pod Identity association:

   ```bash theme={null}
   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](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).

1. Create an IAM OIDC provider for the EKS cluster. You only need to do this once for each cluster.

   ```bash theme={null}
   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:

   ```json theme={null}
   {
     "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:

   ```bash theme={null}
   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.