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

# GCP 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 Google Cloud, the upgrade keeps the existing environment data and instances while moving the console service to Docker image mode.

This guide applies to GCP 7.x environments that need to upgrade to 8.x. For new environments, see [Install AutoMQ on Google Cloud](/automq-cloud/getting-started/install-byoc-environment/google-cloud/install-automq-on-gcp).

## Constraints

* GCP BYOC environments currently support GKE Standard only.
* GCP IaaS and GKE Autopilot are not supported.
* Before the upgrade, confirm that existing GKE clusters, node pools, VPCs, subnets, Cloud DNS private managed zones, and related cloud resources still exist.
* The upgrade requires AutoMQ technical personnel to generate environment metadata and Docker startup parameters.

## Pre-upgrade checks

Confirm the following information:

* You can SSH into the console VM.
* The original console data directory still exists, such as `/home/admin/.cmp/data`.
* The environment ID and deployment region match the current environment.
* The Google Service Account bound to the current VM is still the control plane identity used by the AutoMQ console.

During the GCP upgrade, the console reads some cloud resources during startup. We recommend checking that the console Google Service Account has these read permissions:

| Check item                              | Recommended permission                                                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Read the Cloud DNS private managed zone | At least `dns.managedZones.get`. `roles/dns.reader` or `roles/dns.admin` usually covers this.                          |
| Read the GKE node pool                  | At least `container.nodePools.get`. `roles/container.viewer` or `roles/container.admin` usually covers this.           |
| Read Shared VPC network resources       | In Shared VPC environments, grant network read permissions in the host project, such as `roles/compute.networkViewer`. |

<Tip>
  If the console asks you to initialize permissions after the upgrade, follow the GCP permission instructions on the page and grant the required permissions to the console Google Service Account.
</Tip>

<Tip>
  For GCP GKE clusters created by 7.x, the data plane usually still obtains cloud resource permissions through the VM Service Account bound to the node pool. As long as the node pool still uses instance metadata, and the original VM Service Account still has the required GCS, Cloud DNS, Compute, and related permissions, existing clusters usually continue to run normally.

  8.x introduces a new Workload Identity permission model: AutoMQ Pods use a Kubernetes ServiceAccount to bind to an instance Google Service Account (GSA), and that GSA accesses GCP resources. This model mainly affects data plane permission configuration for clusters created or updated in the 8.x mode.

  Therefore, upgrading the console itself does not require you to immediately change the metadata mode of existing node pools, and it does not require you to immediately remove permissions from the node pool VM Service Account. For existing 7.x clusters, keep the original node pool authorization unchanged during the upgrade to avoid affecting the running data plane.
</Tip>

## Upgrade steps

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

### 1. Register an organization and account

Go to the AutoMQ website and register an organization and account: [https://console.automq.cloud/](https://console.automq.cloud/).

After registration, provide the organization ID to AutoMQ technical personnel.

### 2. Confirm deployment information

Confirm the deployment information of your current BYOC console and send it to AutoMQ technical personnel. This information is used to migrate environment metadata and generate the installation command.

Collect the following information:

* Environment ID
* Deployment region
* Current console version
* Installation ID
* Console endpoint
* Console Google Service Account

We recommend logging in to the old AutoMQ console and checking the settings page. You can also confirm the information from the original startup script, systemd unit, or environment variable file.

### 3. Obtain the upgrade command

AutoMQ technical personnel create or complete the environment record in AutoMQ Cloud based on the current environment information, and then generate the upgrade installation command. The command already contains the environment ID, cloud provider, region, authentication parameters, and Docker image address.

Depending on the target version, the upgrade installation command may use explicit environment variables or a `CONFIG` parameter that carries the encoded environment configuration. Do not assemble these parameters manually.

Before you run the command, confirm that the cloud provider, region, and image version match the current environment. If the image registry requires login, also confirm that you have the Docker registry credentials.

### 4. Stop the old console

SSH into the console VM and stop the old console service. This prevents the old process from writing to the database while you back it up and prevents two console processes from occupying the same ports.

```bash theme={null}
sudo systemctl stop cmp.service
sudo systemctl status cmp.service --no-pager
```

If the old service is configured to restart automatically, disable it during the upgrade window:

```bash theme={null}
sudo systemctl disable cmp.service
```

Confirm that the old process and ports have been released:

```bash theme={null}
ps -ef | grep -E 'cmp|java' | grep -v grep
ss -ltnp | grep -E ':8080|:8085' || true
```

### 5. Back up the database

Back up the local SQLite database after the old console stops. The wildcard also includes any WAL and SHM files.

```bash theme={null}
ts=$(date -u +%Y%m%dT%H%M%SZ)
backup_dir=/home/admin/cmp-migration-backup-$ts
mkdir -p "$backup_dir"

cp -a /home/admin/.cmp/data/sqlite.db* "$backup_dir"/
```

Confirm that the backup files were created and record the backup directory for rollback:

```bash theme={null}
ls -lh "$backup_dir"
echo "$backup_dir"
```

### 6. Install Docker

Install Docker by following the official [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for the VM's operating system. Then confirm that Docker is installed and running:

```bash theme={null}
sudo systemctl start docker
sudo systemctl enable docker
sudo docker version
```

If the image registry requires authentication, log in first and confirm that you can pull the image.

```bash theme={null}
sudo docker login <registry>
sudo docker pull <registry>/automq/automq_byoc_console:<version>
```

### 7. Start the AutoMQ console

Copy the upgrade installation command shown in Step 3 to start the new AutoMQ console. The following command is only a GCP Docker startup example. Use the command generated in Step 3 for the actual upgrade.

The generated command contains credentials. Do not share it or save it in a shared shell history.

```bash theme={null}
sudo docker run -d \
  --name automq-cmp \
  --network host \
  -v /home/admin:/root \
  -e CLOUD_PROVIDER=gcp \
  -e REGION=us-central1 \
  -e ENVIRONMENT_ID=env-xxxx \
  -e OPS_BUCKET=automq-ops-xxxx \
  -e CLIENT_ID=env-xxxx \
  -e CLIENT_SECRET="<client-secret>" \
  -e CONSOLE_INITIAL_USER="<initial-user>" \
  -e CONSOLE_INITIAL_PASSWORD="<strong-initial-password>" \
  <registry>/automq/automq_byoc_console:<version>
```

After you run the upgrade installation command, check the Docker container status and logs:

```bash theme={null}
sudo docker ps
sudo docker logs -f automq-cmp
```

After the Docker container runs correctly and port 8080 is reachable, you can access the AutoMQ console service in your browser.

### 8. Update the License

Because 8.x changes the installation media and startup method, the installation ID may change. After you log in to the new console, if the page shows that the License is invalid, copy the installation ID displayed on the page and contact AutoMQ technical personnel to update the License information.

<Tip>
  A License invalid prompt during the upgrade does not affect existing clusters.
</Tip>

## Roll back

If Docker startup fails and you have not run any instance updates, you can roll back to the original systemd mode.

```bash theme={null}
sudo docker rm -f automq-cmp
backup_dir="<backup-directory-from-step-5>"
cp -a "$backup_dir"/sqlite.db* /home/admin/.cmp/data/
sudo systemctl enable cmp.service
sudo systemctl start cmp.service
sudo systemctl status cmp.service --no-pager
```

If you have already run instance updates, contact AutoMQ technical personnel to confirm the Helm release, Kubernetes resources, and cloud resource states before rolling back the database. Do not overwrite the database until you understand the current cloud resource state.

## Troubleshooting

### Docker container fails to start

Check the following items:

* Whether the Docker image can be pulled.
* Whether the Docker registry token has expired.
* Whether ports 8080 or 8085 are still occupied by the old process.
* Whether `/home/admin` is mounted to `/root` in the container.
* Whether the SQLite files can be read by the container process.

### Console reports insufficient permissions after startup

Check the following items:

* Whether the Google Service Account bound to the console VM is correct.
* Whether the console Google Service Account can read GKE, Cloud DNS, VPC, subnet, and related resources.
* In Shared VPC environments, whether the host project has granted network read permissions.
* Whether you have completed the recommended permissions shown on the console system-init page.