Install AutoMQ on AWS

​

Overview

​

Prerequisites

​

Register Your AutoMQ Environment

1. Visit 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

​

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.

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

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

​

Prepare the ServiceAccount and runtime configuration

apiVersion: v1
kind: Secret
metadata:
  name: <config-secret-name>
  namespace: <console-namespace>
stringData:
  config: "<base64-encoded-runtime-config>"

kubectl apply -f <runtime-config-secret-file>

​

Configure the workload identity

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

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>

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

​

Grant access to the EKS cluster

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

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

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>

nodeAffinities:
  - key: <node-label-key>
    values:
      - <node-label-value>

​

Install AutoMQ Console

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

kubectl get pods,ingress \
  --namespace <console-namespace>

​

Complete initialization

Username: admin
Password: admin

​

Next Steps

• Use AutoMQ via WebUI: Continue to create instances through the environment console and experience the product features. 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.