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

# 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](../getting-started/install-byoc-environment/install-env-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:

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

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

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

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

Register at [AutoMQ Cloud](https://console.automq.cloud/) and provide the organization ID to AutoMQ technical personnel.

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

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

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

```bash theme={null}
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](https://docs.docker.com/engine/install/) for the VM operating system, then verify Docker:

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

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

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

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