Azure BYOC Console Upgrade Guide to v8.x

Background

AutoMQ Console 8.x is distributed and started as a Docker image. For an existing AutoMQ BYOC environment on Azure, the upgrade keeps the environment data and Instances while moving the console service to Docker image mode. This guide applies to Azure 7.x environments that need to upgrade to 8.x. For a new environment, see Install AutoMQ on Azure.

Constraints

The existing Azure BYOC environment uses AKS as its data plane Kubernetes cluster.
Confirm that the AKS cluster, node pool, VNet, Subnet, Private DNS Zone, Storage Account, and Blob containers still exist.
AutoMQ technical personnel must help migrate the environment metadata and generate the Docker startup command.
Resource names in this guide are examples. Use the Terraform output and Azure resources from your environment.

Pre-upgrade checks

Confirm that:

You can SSH into the console VM.
The original console data directory still exists, for example /home/admin/.cmp/data, and its host path is on the mounted persistent disk.
The environment ID and Region match the current environment.
The Console UAMI is still bound to the VM.
The persistent disk that contains the console home directory is mounted, and the SQLite -wal and -shm files are accessible.

Check the AKS identity configuration

Check the AKS configuration before upgrading the console. Before you update an existing Instance to 8.x or create a new 8.x Instance, make sure the required data plane identity features are enabled:

Microsoft Entra integration: Recommended. It allows the console to access AKS as the Console UAMI instead of using a static clusterAdmin kubeconfig. If it is disabled, the console uses the existing static administrator access during the upgrade.
Azure RBAC for Kubernetes Authorization: Recommended when Microsoft Entra integration is enabled. It allows you to grant the console’s Kubernetes permissions through Azure IAM. If it is disabled, a cluster administrator can maintain a Kubernetes ClusterRoleBinding for the Console UAMI principal after the upgrade.
OIDC issuer: Required before an Instance uses Azure Workload Identity.
Workload Identity: Required before an Instance uses Azure Workload Identity.

Check all four settings:

az aks show \
  --resource-group <aks-resource-group> \
  --name <aks-name> \
  --query '{entraIntegration:aadProfile.managed,azureRbac:aadProfile.enableAzureRbac,oidcIssuer:oidcIssuerProfile.enabled,workloadIdentity:securityProfile.workloadIdentity.enabled}' \
  -o yaml

Before an Instance update, verify that oidcIssuer and workloadIdentity are true. We also recommend setting entraIntegration and azureRbac to true. Do not add new 8.x permissions before the console upgrade; keep the existing Console UAMI assignments and data plane identity unchanged. The existing workload UAMI and its current permissions do not need to change for the console upgrade. New 8.x Instances require an AKS OIDC Federated Identity Credential whose subject matches its Kubernetes ServiceAccount. Useful inspection commands include:

az vm show -g <resource-group> -n <console-vm> --query identity
az network private-dns zone show -g <resource-group> -n <private-dns-zone>
az storage account show -g <resource-group> -n <storage-account>

A 7.x AKS cluster may still use the node pool VMSS identity for data plane access. Upgrading the console does not require immediately changing that identity. Keep the existing data plane authorization unchanged during the upgrade. New 8.x Instances use Azure Workload Identity.

Upgrade steps

The overall process is to register an AutoMQ account, confirm deployment information, obtain the upgrade command, stop the old console, back up the database, install Docker, start and verify the new console, and update the License.

1. Register an organization and account

2. Confirm deployment information

Collect and send the following information to AutoMQ technical personnel:

Environment ID, Region, current console version, and installation ID.
Console endpoint.
Azure Subscription ID, Resource Group, and AKS cluster name.
Storage Account and Ops Blob container.
Console UAMI.

Use the old console settings page, Terraform output, Azure Portal, or Azure CLI to confirm these values.

3. Obtain the upgrade command

AutoMQ technical personnel use the current environment information to migrate the environment record and generate an Azure 8.x installation command. It contains the complete Base64 CONFIG, CLOUD_PROVIDER=azure, initial administrator settings, and Docker image address. Copy the complete command directly. Do not decode, split, or manually assemble CONFIG. Ask AutoMQ technical personnel to confirm that the command matches the environment and target version. Record the host mount source from the generated command and reuse it in later commands. Confirm that the host mount source is on the persistent disk and that the container target is /root:

CONSOLE_HOME="<host-mount-source-from-generated-command>"
findmnt -T "$CONSOLE_HOME"
test -r "$CONSOLE_HOME/.cmp/data/sqlite.db"

4. Stop the old console

Stop the old service to prevent database writes and port conflicts:

sudo systemctl stop cmp.service
sudo systemctl status cmp.service --no-pager
sudo systemctl disable cmp.service

ps -ef | grep -E 'cmp|java' | grep -v grep
ss -ltnp | grep -E ':8080|:8085' || true

5. Back up the database

Back up SQLite after the service stops. The wildcard includes WAL and SHM files.

ts=$(date -u +%Y%m%dT%H%M%SZ)
backup_dir="$CONSOLE_HOME/cmp-migration-backup-$ts"
mkdir -p "$backup_dir"

sudo cp -a "$CONSOLE_HOME"/.cmp/data/sqlite.db* "$backup_dir"/

ls -lh "$backup_dir"

6. Install Docker

Follow the official Docker Engine installation instructions for the VM operating system, then verify Docker:

sudo systemctl enable --now docker
sudo docker version

7. Start the AutoMQ console

Run the complete upgrade command from Step 3. The following command only illustrates the startup shape. The CONFIG value and image must come from the same generated command. The generated command contains credentials. Do not share it or save it in shared shell history.

sudo docker run -d \
  --name automq-cmp \
  --restart unless-stopped \
  -v "$CONSOLE_HOME:/root" \
  --net=host \
  -e CONFIG="<complete-base64-config>" \
  -e CLOUD_PROVIDER=azure \
  -e CONSOLE_INITIAL_USER=admin \
  -e CONSOLE_INITIAL_PASSWORD="<strong-initial-password>" \
  <image-from-generated-command>

Check the container and logs:

sudo docker ps
sudo docker logs -f automq-cmp

When the container is healthy and port 8080 is reachable, open the console in your browser.

8. Verify the upgrade

Complete these checks before any Instance update:

The Environment ID, Region, and Console version match the target environment.
Existing Instances are visible and remain healthy.
System Initialization is healthy. After the upgrade, open this page and grant the roles and scopes it currently requires. Do not preconfigure these 8.x permissions before the upgrade.
Console logs have no persistent database, Azure authentication, or cloud resource permission errors.
Existing AKS workloads remain healthy, and current application Kafka connections still work.

Do not modify or upgrade an Instance until these checks pass. If validation fails before an Instance update, you can use the console rollback below. After an Instance update, contact AutoMQ technical personnel to assess the cloud resource state first.

9. Update the License

The installation ID may change in 8.x. If the new console reports an invalid License, copy the displayed installation ID and contact AutoMQ technical personnel to update it. This prompt does not affect existing clusters.

Roll back

If Docker startup or pre-update validation fails and no Instance update has been performed, stop and remove the new Docker container, restore the SQLite backup, and start the original systemd service:

sudo docker rm -f automq-cmp
backup_dir="<backup-directory-from-step-5>"
sudo cp -a "$backup_dir"/sqlite.db* "$CONSOLE_HOME/.cmp/data/"
sudo systemctl enable cmp.service
sudo systemctl start cmp.service
sudo systemctl status cmp.service --no-pager

If an Instance update has already been performed, contact AutoMQ technical personnel to confirm the Helm release, Kubernetes resources, Azure RBAC, Blob, and Private DNS state before restoring the database.

Troubleshooting

Docker container fails to start

Check:

The Docker image can be pulled.
Ports 8080 and 8085 are not occupied by the old process.
The generated host path is mounted to container /root and remains on the persistent disk.
The container process can read the SQLite files.
The Console UAMI can read the required AKS, Private DNS, and Blob resources.

Console reports insufficient permissions after startup

Check:

The correct Console UAMI is bound to the console VM.
The Console UAMI can read AKS, VMSS, Private DNS, VNet, Subnet, and Storage Account resources.
The Blob endpoint and Ops container match the environment.
The Private DNS Zone is linked to the selected VNet.
The permissions on the current System Initialization page have been granted.

Overview

Getting Started

Deploy on Kubernetes

Subscriptions and Billings

Manage Environments

Manage Identities and Access

Managing AutoMQ

Migrate to AutoMQ

Manage Security

Kafka Connect

Monitoring & Alert

Table Topic

Best Practice

Eliminate Inter-Zone Traffics

Release Notes

Support

Appendix

Azure BYOC Console Upgrade Guide to v8.x

Background

Constraints

Pre-upgrade checks

Check the AKS identity configuration

Upgrade steps

1. Register an organization and account

2. Confirm deployment information

3. Obtain the upgrade command

4. Stop the old console

5. Back up the database

6. Install Docker

7. Start the AutoMQ console

8. Verify the upgrade

9. Update the License

Roll back

Troubleshooting

Docker container fails to start

Console reports insufficient permissions after startup

​Background

​Constraints

​Pre-upgrade checks

​Check the AKS identity configuration

​Upgrade steps

​1. Register an organization and account

​2. Confirm deployment information

​3. Obtain the upgrade command

​4. Stop the old console

​5. Back up the database

​6. Install Docker

​7. Start the AutoMQ console

​8. Verify the upgrade

​9. Update the License

​Roll back

​Troubleshooting

​Docker container fails to start

​Console reports insufficient permissions after startup

Background

Constraints

Pre-upgrade checks

Check the AKS identity configuration

Upgrade steps

1. Register an organization and account

2. Confirm deployment information

3. Obtain the upgrade command

4. Stop the old console

5. Back up the database

6. Install Docker

7. Start the AutoMQ console

8. Verify the upgrade

9. Update the License

Roll back

Troubleshooting

Docker container fails to start

Console reports insufficient permissions after startup