Skip to main content
As described in Overview, AutoMQ supports deployment on Kubernetes. This article describes how to prepare Azure Kubernetes Service (AKS) for AutoMQ 8.x.

​
Install the environment console

Before you begin, follow Install AutoMQ on Azure to install the AutoMQ console with Docker and complete System Initialization. To prepare the console, AKS, and example resources with Terraform, see the AutoMQ Azure Terraform example.

​
Prepare the AKS cluster and node pool

​
Step 1: Create the AKS cluster

Create a Standard AKS cluster. The AutoMQ console must access the AKS Kubernetes API to create and manage an Instance.

​
Console UAMI access to AKS

The console should access AKS with its own identity instead of a shared static administrator credential. We recommend enabling Microsoft Entra integration:
  • The console authenticates as the Console UAMI with Microsoft Entra tokens.
  • The console uses a clusterUser kubeconfig, so Kubernetes requests carry the console identity.
If Microsoft Entra integration is disabled, the console accesses AKS with a static clusterAdmin kubeconfig obtained through the Azure API. Grant the Console UAMI Azure Kubernetes Service Cluster Admin Role to obtain it.

​
Console Kubernetes permissions

After authentication is configured, choose where to manage the console’s Kubernetes permissions. We recommend managing them centrally in Azure IAM instead of maintaining a separate Kubernetes RBAC configuration. With Microsoft Entra integration enabled, we recommend enabling Azure RBAC for Kubernetes Authorization:
  • Grant the Console UAMI Azure Kubernetes Service RBAC Cluster Admin at the target AKS cluster scope.
  • Grant the AKS access permission generated on the System Initialization page. It must include Microsoft.ContainerService/managedClusters/listClusterUserCredential/action, which lets the console obtain the clusterUser kubeconfig. This permission does not grant Kubernetes management permissions by itself.
If Azure RBAC for Kubernetes Authorization is disabled, AKS uses native Kubernetes RBAC. Grant the AKS access permission generated on the System Initialization page, then have a cluster administrator create and maintain a Kubernetes ClusterRoleBinding for the Console UAMI principal. Use the Azure authorization commands generated on that page.

​
Data plane access to Azure resources

AutoMQ data plane Pods use Azure Workload Identity to access Azure resources. To use this authentication mechanism, enable both the AKS OIDC issuer and Workload Identity features.

​
Network and egress

The console must reach the cluster, and the nodes must pull images and call Azure APIs. AutoMQ service ports must also be reachable:
  • Use Azure CNI Node Subnet. When creating the AKS cluster, explicitly set --network-plugin azure and don’t set --network-plugin-mode overlay. Make sure the console can access Pod IPs directly from outside the AKS cluster.
  • Make sure the console can reach the AKS API Server and AutoMQ service ports.
  • Make sure nodes can reach container registries, Azure APIs, and external services required by AutoMQ.

​
Availability zones for production

Place nodes across three Availability Zones in production to reduce the impact of a zone failure.

​
Step 2: Check network access paths

Before creating an Instance, check the NSGs, routes, firewalls, and DNS configuration for these paths:
  • The AutoMQ console can reach the AKS API Server.
  • The AutoMQ console can reach the AutoMQ data plane Pod or Service ports.
  • Kafka client networks can reach the AutoMQ service ports required by your applications.
  • AKS nodes can reach container registries, Azure APIs, and external services required by AutoMQ. Nodes without Public IPs need a NAT Gateway or another egress path.
  • For a private AKS API Server, the console VM must have connectivity to the AKS VNet and resolve the AKS private DNS name.
  • For a public AKS API Server with authorized IP ranges enabled, those ranges must include the console egress address.
Run the following command to check the AKS network configuration:
Confirm that networkPlugin is azure and networkPluginMode isn’t overlay. We recommend at least 512 IP addresses in the AKS Subnet. Common AutoMQ service ports include 8083, 9090, 9092, 9093, 9102, 9103, 9112, and 9113. The console Subnet is a required source. Add Kafka client CIDR ranges only when those clients need application access. Use NSGs or equivalent network policies to restrict sources to the required CIDR ranges. Allow node DNS resolution and outbound TCP 443.

​
Step 3: Prepare the dedicated AutoMQ node pool

Create a separate User node pool for AutoMQ Brokers and configure:
  • A VM size and node count based on Overview.
  • Three Availability Zones and Cluster Autoscaler for production.
  • Taint: dedicated=automq:NoSchedule.
The AutoMQ 8.x data plane uses Azure Workload Identity. Do not bind the workload UAMI to the node pool VMSS. Node identity no longer carries AutoMQ data plane permissions.

​
Step 4: Prepare the AutoMQ workload identity

AutoMQ data plane Pods use Azure Workload Identity to access Blob Storage, Private DNS, and Managed Disks. Select one of these modes when creating an Instance: For Customer-Provided mode, enter the workload UAMI full ARM resource ID, not its client ID or principal ID. The KSA azure.workload.identity/client-id annotation uses the UAMI client ID. The console checks the identity configuration, but you must still ensure that the identity can access both the Ops Bucket and Data Bucket Blob containers, the Private DNS Zone, and the Managed Disk resources.

​
Create an AutoMQ Instance

Sign in to the AutoMQ console, create an Instance, select Kubernetes deployment, and configure: Do not replace an ARM ID with a display name, Resource Group/name tuple, UAMI client ID, or principal ID. The current scope supports AKS in Azure Public Cloud and resources in the same tenant and Subscription. Resources can be in different Resource Groups. Azure IaaS, cross-subscription resources, cross-tenant resources, and Public DNS lifecycle are not supported.
  1. AKS cluster: Select the target cluster. APIs and automation use its full ARM ID: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ContainerService/managedClusters/<aks-name>.
  2. Node pool: Enter the node pool short name within the selected AKS cluster.
  3. Virtual Network: Enter the selected VNet full ARM ID. Kubernetes deployment does not use a Subnet as a workload placement input.
  4. Data bucket: Select a Managed resource or enter a Customer-Provided Blob container. An Azure Bucket ID uses <storage-account>:<container>.
  5. Private DNS Zone: Select a Managed resource or enter the full ARM ID of a Customer-Provided Private DNS Zone. A Customer-Provided Zone must already have a resolution-only VNet Link to the selected VNet.
  6. Instance identity: Select Managed identity or enter the full ARM ID of a Customer-Provided UAMI.
  7. Namespace and ServiceAccount: For Customer-Provided identity, enter the values represented by the Federated Identity Credential subject.
  8. Preview the configuration and complete creation.
AKS, VNet, and node pool are always Customer-Provided dependencies. Data bucket, Private DNS Zone, and workload UAMI can be Managed or Customer-Provided. The console does not modify or delete Customer-Provided root resources. It still reads and writes Blob objects and maintains and cleans up Instance-owned DNS records during the Instance lifecycle.

​
Appendix: Deploy a Placeholder Deployment (optional)

To reserve failover capacity in the AutoMQ node pool, deploy low-priority Placeholder Pods. A Broker can preempt this capacity during failover.
  1. Download and create the low-priority PriorityClass:
  2. Download the AKS Placeholder manifest:
  3. Update automq-aks-placeholder.yaml for the actual node pool:
    • metadata.name: Use a recognizable name.
    • replicas: Set the number of nodes to reserve. For a multi-zone deployment, evaluate reserving one Pod per zone.
    • affinity.nodeAffinity: Match the dedicated AutoMQ node pool with the native AKS label kubernetes.azure.com/agentpool=<node-pool-name>.
    • resources: Set limits based on node size and set requests slightly below the node allocatable resources.
  4. Deploy the manifest and confirm that the Pods run on the expected node pool:

​
Next steps

After Instance creation, confirm that the Instance is healthy, AutoMQ Pods run on the dedicated node pool, Private DNS resolves from the target VNet, and Kafka connectivity works from the expected client network.