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

# Install AutoMQ on AWS

> This article describes how to install the AutoMQ console on AWS and complete the initial configuration to prepare for creating and managing AutoMQ clusters.

## Overview

To use the AutoMQ Cloud BYOC environment on AWS, you first need to install the AutoMQ console. The console is a web application deployed in your account that you will use to create, manage, and monitor your AutoMQ clusters.

## Prerequisites

The AutoMQ Console can be deployed directly to Amazon EC2 or Amazon EKS. Prepare the resources required by the deployment option that you select.

| Deployment option | Required resources | Preparation guide |
| - | - | - |
| Amazon EC2 | A VPC for the AutoMQ Console and AutoMQ instances. Use the VPC that contains your Kafka applications when possible. | [Prepare a VPC](/automq-cloud/getting-started/install-byoc-environment/aws/prepare-vpc) |
| Amazon EKS | A VPC and an existing EKS cluster with the required compute, networking, storage, and identity configuration. | [Prepare a VPC](/automq-cloud/getting-started/install-byoc-environment/aws/prepare-vpc) and [Deploy to Amazon EKS](/automq-cloud/deploy-automq-on-kubernetes/deploy-to-aws-eks) |

## Register Your AutoMQ Environment

First, you need to register your deployment environment on the AutoMQ official website to obtain the metadata for environment installation.

1. Visit [AutoMQ Cloud](https://account.automq.cloud) and log in to your account.
2. On the console page, click **Create Environment**.
3. Follow the wizard to enter the following information:
   * **Environment Name**: Set a custom name for your environment.
   * **Description**: Enter a description for the environment.
   * **Cloud Provider**: Select **AWS**.
   * **Region**: Select the AWS region where you plan to deploy AutoMQ.
4. After creation, you will receive the environment metadata for deployment.

## Deploy AutoMQ Console on EC2

### Prepare and Deploy the Console EC2 Instance

The AutoMQ console is the core component for managing the AutoMQ Cloud BYOC environment, and it is deployed on a standalone EC2 instance. Therefore, you need to prepare this EC2 instance before installation.

#### Basic Requirements

To ensure the stable operation of the console, the EC2 instance you prepare needs to meet the following basic requirements:

1. **Instance Specifications**:
   * **Configuration**: At least a **2-core CPU** and **8 GB of memory**.
   * **System Volume**: At least **20 GiB** of storage space.
   * **Data Volume**: An additional data volume of at least **20 GiB** must be mounted to store metadata.

> [!TIP]
>
> **Important Note**: To prevent metadata loss from the console due to EC2 instance migration or failure, it is crucial to mount an additional data volume to the EC2 instance for the AutoMQ console and store the metadata on this volume.

2. **Network Location**:
   * The EC2 instance **must** be located in the same VPC as the AutoMQ cluster that will be deployed later.
   * Typically, this VPC should also be the same as the one where your application services are located to ensure network connectivity.

3. **Public Access**:
   * The EC2 instance must have internet access to download installation packages and synchronize necessary metadata. You can achieve this by associating an Elastic IP (EIP) or by configuring a NAT gateway.

#### Creation and Deployment Steps

1. Log in to the AWS [EC2 console](https://console.aws.amazon.com/ec2/home) and click **Launch instances**.

2. **Operating System (AMI)**: Choose a Linux distribution you are familiar with, such as Amazon Linux 2023 or Ubuntu.

3. **Instance Type**: Select an instance type that meets the above specifications (e.g., `t3.large` or higher).

4. **Network Settings**:
   * Select the target VPC and a public subnet (if using an EIP) or a private subnet (if using a NAT gateway).
   * Ensure the security group opens necessary ports, such as SSH (22) for management access and the console's service port (default 8080). Restrict the source to trusted IP ranges.

5. **Storage (Volumes)**:
   * Configure the root volume size to at least 20 GiB.
   * Click **Add new volume** to add an additional data volume, ensuring its size is not less than 20 GiB.

6. Complete the remaining configurations and launch the instance.

7. **Mount the Data Volume**:
   * After the instance starts, log in to it.
   * Mount the additional data volume to a specified directory (e.g., `/data`). This path will be used as the data mount path when starting the Docker container.
   * Ensure the mount point has the correct permissions.

8. **Install and Start Docker Service**:

   * Install Docker on the EC2 instance. The following are reference commands for Amazon Linux 2023:

   ```bash theme={null}
   # Update packages
   sudo dnf update -y
   # Install Docker
   sudo dnf install docker -y
   # Start the Docker service
   sudo systemctl start docker
   # Add the current user to the docker group to run docker commands without sudo
   sudo usermod -aG docker ec2-user
   # Enable the Docker service to start on boot
   sudo systemctl enable docker
   # Verify Docker installation
   docker version
   ```

   * **Note**: If you are using another Linux distribution (like Amazon Linux 2), refer to the official Docker documentation or use the appropriate package manager for installation.

9. **Deploy the AutoMQ Console**
   * Once the EC2 instance is ready, you can copy the installation command from the installation wizard to start the AutoMQ console.

### Configure Console Permissions and Complete Initialization

After the AutoMQ console starts successfully, you need to log in to the console. On your first visit, you will need to grant it the necessary permissions to operate AWS cloud resources.

1. **Log in to the Console**
   * Access `http://<Your EC2 Public IP>:8080` in your browser.
   * Log in with the initial username and password.

2. **Grant IAM Permissions to the Console**
   After logging in, the interface will guide you to complete IAM authorization for the AutoMQ console. This is to allow the console to have permission to create and manage cluster resources in your AWS account. The process is as follows:

   1. **Create an IAM Policy**:
      * Go to the AWS IAM console and create a new customer-managed policy based on the policy JSON provided in the console interface.

   2. **Create an IAM Role**:
      * Create a new IAM Role.
      * When selecting the trusted entity, choose **AWS service** and **EC2**.
      * Attach the IAM Policy created in the previous step to this Role.

   3. **Associate the IAM Role with the EC2 Instance**:
      * Go to the AWS EC2 console and find the EC2 instance you are using to deploy the console.
      * In **Actions** -> **Security** -> **Modify IAM role**, associate the IAM Role created in the previous step with this instance.

3. **Complete Initialization**
   * Return to the AutoMQ console page and click **Confirm Authorization** or **Next**.
   * The console will automatically verify if the permissions are configured correctly. Once verified, you can officially enter the AutoMQ console and start creating your first cluster.

## Deploy AutoMQ Console on EKS

This section deploys AutoMQ Console as a Helm release in Amazon EKS. Before you begin, [prepare the EKS cluster and compute resources](/automq-cloud/deploy-automq-on-kubernetes/deploy-to-aws-eks#prepare-eks-cluster-and-compute-resources) and keep the deployment configuration generated by the environment installation wizard available.

The following commands and manifests use `<...>` placeholders. Replace them with the corresponding resource identifiers from your environment.

### Prepare the ServiceAccount and runtime configuration

Before installing the Chart, ensure that the target namespace and ServiceAccount exist. You can reuse existing resources or prepare them through your own resource management process. The Chart references `<console-service-account>` in `<console-namespace>` but does not create or modify it.

The environment installation wizard provides the same base64-encoded deployment configuration used by the EC2 Docker deployment.

Prepare a Secret whose lowercase `config` key contains the complete base64 string generated by the installation wizard. Replace `<config-secret-name>` with the Secret name, `<console-namespace>` with the namespace where the console runs, and `<base64-encoded-runtime-config>` with the configuration generated by the installation wizard:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: <config-secret-name>
  namespace: <console-namespace>
stringData:
  config: "<base64-encoded-runtime-config>"
```

Save the manifest to a local file and replace `<runtime-config-secret-file>` with its path:

```bash theme={null}
kubectl apply -f <runtime-config-secret-file>
```

### Configure the workload identity

Bind the IAM role to the ServiceAccount with EKS Pod Identity or IRSA. EKS Pod Identity is recommended for new EKS deployments.

**EKS Pod Identity**

1. Confirm that the EKS Pod Identity Agent is installed. EKS Auto Mode includes the agent.
2. Prepare or select an IAM role with this trust policy:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}
```

3. Ensure that the role is associated with the ServiceAccount. If it is not already associated, run the following command. `<eks-cluster-name>` is the target EKS cluster, `<console-namespace>` and `<console-service-account>` identify the ServiceAccount used by the console, `<aws-account-id>` and `<console-role-name>` identify the IAM role, and `<aws-region>` is the region of the EKS cluster:

```bash theme={null}
aws eks create-pod-identity-association \
  --cluster-name <eks-cluster-name> \
  --namespace <console-namespace> \
  --service-account <console-service-account> \
  --role-arn "arn:aws:iam::<aws-account-id>:role/<console-role-name>" \
  --region <aws-region>
```

For more information, see [Learn how EKS Pod Identity grants pods access to AWS services](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).

**IRSA**

1. Confirm that the EKS cluster has an IAM OIDC provider.
2. Prepare or select an IAM role whose trust policy allows `sts:AssumeRoleWithWebIdentity` for this ServiceAccount.
3. Ensure that the ServiceAccount has the role ARN annotation. If it is not already configured, run the following command. `<console-service-account>` and `<console-namespace>` identify the ServiceAccount used by the console, while `<aws-account-id>` and `<console-role-name>` identify the IAM role:

```bash theme={null}
kubectl annotate serviceaccount <console-service-account> \
  --namespace <console-namespace> \
  "eks.amazonaws.com/role-arn=arn:aws:iam::<aws-account-id>:role/<console-role-name>"
```

For the required trust policy, see [IAM roles for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).

### Grant access to the EKS cluster

AutoMQ Console uses the same IAM role to manage Kubernetes resources. Ensure that the role has a standard EKS access entry with the cluster-scoped `AmazonEKSClusterAdminPolicy`. If it is not already configured, run the following commands. `<eks-cluster-name>` is the target EKS cluster, `<aws-account-id>` and `<console-role-name>` identify the IAM role associated with the ServiceAccount, and `<aws-region>` is the region of the EKS cluster:

```bash theme={null}
aws eks create-access-entry \
  --cluster-name <eks-cluster-name> \
  --principal-arn "arn:aws:iam::<aws-account-id>:role/<console-role-name>" \
  --type STANDARD \
  --region <aws-region>

aws eks associate-access-policy \
  --cluster-name <eks-cluster-name> \
  --principal-arn "arn:aws:iam::<aws-account-id>:role/<console-role-name>" \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster \
  --region <aws-region>
```

### Configure the Helm values

Set the following values in your Helm values file:

* `<config-secret-name>`: The runtime configuration Secret prepared above.
* `<aws-account-id>`: The AWS account where the console is deployed.
* `<vpc-id>`: The VPC that contains the EKS cluster.
* `<alb-subnet-id-1>` and `<alb-subnet-id-2>`: Subnets in different Availability Zones where the ALB will be created.
* `<console-service-account>`: The ServiceAccount already associated with the IAM role.
* `<storage-class-name>`: An existing StorageClass in the target EKS cluster that supports dynamic `ReadWriteOnce` provisioning, typically provided by the Amazon EBS CSI driver. Run `kubectl get storageclass` to list available StorageClasses.
* `<console-domain-name>`: The domain name used to access the console.
* `<acm-certificate-arn>`: The ARN of an ACM certificate that matches the console domain.

```yaml theme={null}
automqByocConsole:
  config:
    existingSecret: <config-secret-name>

aws:
  account: "<aws-account-id>"
  network:
    vpcId: <vpc-id>
    subnetIds:
      - <alb-subnet-id-1>
      - <alb-subnet-id-2>

serviceAccount:
  name: <console-service-account>

persistence:
  storageClass: <storage-class-name>

ingress:
  enabled: true
  host: <console-domain-name>
  alb:
    scheme: internet-facing
    protocol: HTTPS
    certificateArn: <acm-certificate-arn>
```

The ALB subnets expose AutoMQ Console and are independent of the NLB subnets selected when you create an AutoMQ instance. To keep the endpoint private, set `ingress.alb.scheme` to `internal` and use private subnets.

The Chart does not constrain pod placement by default. If the EKS cluster has dedicated nodes for AutoMQ Console, add their label as a required affinity. Replace `<node-label-key>` and `<node-label-value>` with a label key and value that already exist on the target nodes:

```yaml theme={null}
nodeAffinities:
  - key: <node-label-key>
    values:
      - <node-label-value>
```

### Install AutoMQ Console

Install the Chart from the AutoMQ OCI registry. The latest recommended stable Chart version is `8.3.7`. Replace `<release-name>` with the Helm release name, `<console-namespace>` with the namespace where the console runs, and `<values-file>` with the path to the values file prepared above:

```bash theme={null}
helm upgrade --install <release-name> \
  oci://automq.azurecr.io/helm/automq-byoc-console-chart \
  --version 8.3.7 \
  --namespace <console-namespace> \
  --values <values-file> \
  --wait
```

Wait for the pod and Ingress to become ready. Replace `<console-namespace>` with the namespace where the console runs:

```bash theme={null}
kubectl get pods,ingress \
  --namespace <console-namespace>
```

Create the DNS record for the hostname in `ingress.host` and point it to the ALB hostname shown in the Ingress status.

### Complete initialization

Open `https://<console-domain-name>` and sign in with the temporary bootstrap credentials:

```text theme={null}
Username: admin
Password: admin
```

> [!WARNING]
>
> These credentials are public bootstrap credentials. Restrict access to the ALB and change the password immediately after the first sign-in.

The initialization page displays the IAM policy required by AutoMQ Console. Create a customer-managed policy from that JSON and attach it to the same IAM role associated with the ServiceAccount. Return to AutoMQ Console and confirm the authorization.

After the permission check succeeds, you can create and manage AutoMQ instances.

## Next Steps

* **Use AutoMQ via WebUI:** Continue to create instances through the environment console and experience the product features. [Experience AutoMQ▸](/automq-cloud/getting-started/experience-automq)
* **Use AutoMQ via Terraform:** After installing the console, users can manage and use AutoMQ through the AutoMQ Terraform Provider. For using AutoMQ via Terraform, [refer to the documentation](https://registry.terraform.io/providers/AutoMQ/automq/latest/docs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.