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

# Install AutoMQ on Google Cloud

> This article describes how to install the AutoMQ console on Google Cloud with Docker and complete the initial permission configuration before deploying to GKE.

## Overview

To use an AutoMQ BYOC environment on Google Cloud, you first need to install the AutoMQ console. The console is a web application deployed in your Google Cloud project. You use it to create, manage, and monitor AutoMQ clusters.

Starting from 8.x, the AutoMQ console is distributed and started as a Docker image. New environments should use the Docker installation method.

## Prerequisites

Before you begin installing the AutoMQ console, prepare the required Google Cloud network resources.

* **VPC environment**: The AutoMQ console and GKE cluster need to run in your VPC, usually the same VPC as your Kafka client applications or a VPC that can reach them.

## Steps

### Step 1: Register your environment on the AutoMQ website

First, register your deployment environment on the AutoMQ website to obtain the environment metadata and Docker startup command.

1. Visit [AutoMQ Cloud](https://account.automq.cloud) and log in to your account.
2. On the console page, click **Create Environment**.
3. Follow the wizard to enter the environment name, cloud provider, region, and related information.
4. After creation, copy the Docker startup command generated by the installation wizard.

### Step 2: Prepare and deploy the console VM

The AutoMQ console needs to run on a standalone Google Cloud VM. The VM should be in the VPC used by the GKE cluster that you will deploy later.

On GCP, the AutoMQ console running on the VM calls Google Cloud APIs through the Google Service Account bound to that VM. To avoid using the default Compute Engine service account, create a dedicated service account in the service project where the console runs before you create the VM. This document refers to it as the console Google Service Account.

The console Google Service Account is the control plane identity for the AutoMQ console. During permission initialization, you grant this service account the permissions needed to manage GKE, GCS, Cloud DNS, IAM bindings, and other cloud resources required by AutoMQ. At this point, you only need to create the service account and bind it to the VM when you create the VM. You don't need to grant the full AutoMQ permissions in advance. After the console starts, the initialization page shows the permissions that need to be granted to this service account and guides you through authorization and verification.

If you use `gcloud` to create the console Google Service Account, use the following example:

```bash theme={null}
PROJECT_ID="<service-project-id>"
CONSOLE_SA_ID="automq-console"

gcloud iam service-accounts create "${CONSOLE_SA_ID}" \
  --project="${PROJECT_ID}" \
  --display-name="AutoMQ console"
```

#### Basic requirements

For stable console operation, we recommend the following VM configuration:

1. **Instance specifications**
   * At least **2 vCPUs** and **8 GB memory**.
   * At least **20 GiB** system disk.
   * Use a separate data disk or a stable data directory for console data.

2. **Network location**

   * The console VM should be in a VPC and subnet reachable from the GKE cluster.
   * If you use Shared VPC, confirm the permission boundary between the service project where the console runs and the host project where the VPC resides.
   * The console service listens on port `8080` by default. Allow your operations access source to reach port `8080` on the console VM, and restrict the source CIDR ranges to your office network, bastion host, or another approved access path.

   If you use `gcloud` to create the firewall rule, use the following command as a reference. It narrows the target to VMs bound to the console Google Service Account by using `--target-service-accounts`. `NETWORK_PROJECT_ID` is the project that owns the VPC and firewall rules. In non-Shared VPC environments, it is usually the service project.

   ```bash theme={null}
   NETWORK_PROJECT_ID="<network-project-id>"
   VPC_NAME="<vpc-name>"
   CONSOLE_SA_EMAIL="<console-service-account-email>"
   SOURCE_CIDR="<operator-source-cidr>"

   gcloud compute firewall-rules create "automq-console-allow-8080" \
     --project="${NETWORK_PROJECT_ID}" \
     --network="${VPC_NAME}" \
     --direction=INGRESS \
     --action=ALLOW \
     --source-ranges="${SOURCE_CIDR}" \
     --target-service-accounts="${CONSOLE_SA_EMAIL}" \
     --rules=tcp:8080
   ```

3. **Internet access or egress capability**
   * The console VM needs to pull Docker images and synchronize required metadata. Use an external IP, Cloud NAT, or another egress path.
   * If the console VM doesn't use an external IP and doesn't have Cloud NAT or another egress path, enable Private Google Access on the subnet that hosts the console VM so it can reach Cloud Storage, GKE, IAM, Cloud DNS, and other Google APIs. This configuration only covers Google API access. If the VM needs to reach external image registries or other non-Google endpoints, it still needs an external IP, Cloud NAT, or another egress path. For details, see the Google Cloud documentation [Configure Private Google Access](https://docs.cloud.google.com/vpc/docs/configure-private-google-access).

4. **VM service account**
   * When you create the VM, bind the console Google Service Account prepared earlier to the VM. This is the same service account you created at the beginning of this step, and the later permission initialization also applies to this service account.
   * The operator who creates the VM needs the `iam.serviceAccounts.actAs` permission on this service account to bind it to the VM.
   * Set the VM access scope to allow full access to all Cloud APIs (`https://www.googleapis.com/auth/cloud-platform`). Google Cloud's default access scopes only include limited permissions such as read-only Cloud Storage, Logging, and Monitoring.
   * Even if the console Google Service Account has the required IAM roles, a restrictive VM access scope can still block calls to GKE, IAM, Cloud DNS, or write operations to GCS. For details, see the Google Cloud documentation [Create a VM that uses a user-managed service account](https://docs.cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances).

#### Install and start Docker

Log in to the console VM, then install and start Docker. The following commands use Debian / Ubuntu as an example:

```bash theme={null}
sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo docker version
```

#### Start the AutoMQ console

After the VM is ready, copy the Docker startup command generated by the installation wizard in Step 1 and start the AutoMQ console.

<Tip>
  The command generated by the installation wizard already contains the environment ID, cloud provider, region, authentication parameters, Docker image address, and related information. Do not assemble these parameters manually.
</Tip>

After you run the startup command, check the container status and logs:

```bash theme={null}
sudo docker ps
sudo docker logs -f "<container-name-or-id>"
```

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

### Step 3: Configure console permissions and complete initialization

After the AutoMQ console starts successfully, the first login may ask you to initialize permissions. Follow the GCP permission instructions on the page and grant the required permissions to the console Google Service Account.

Permission initialization allows the AutoMQ console to create and manage cloud resources. In GCP, the console VM calls Google Cloud APIs through the bound console Google Service Account. Follow the page instructions and grant the listed permissions to this service account. The console verifies those permissions during initialization.

GCP permissions can be granted at different locations depending on the capability. In non-Shared VPC environments, the service project and host project are usually the same project. In Shared VPC environments, GKE, the console VM, buckets, and Google Service Accounts usually reside in the service project, while VPC, subnet, and firewall resources reside in the host project. Some bucket and Cloud DNS permissions may also need to be granted on the target resource. The following table helps you understand the bindings shown on the initialization page. Grant permissions based on the content generated on that page.

| Capability                                 | Recommended binding location                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Console system data management             | Bucket shown on the initialization page                       | The console reads and writes system logs, metrics, and other runtime data, and maintains the bucket IAM policy. Recommended role: `roles/storage.admin`.                                                                                                                                                                                                                                                                                                                            |
| GKE and network discovery                  | Service project and host project                              | The console reads GKE Standard clusters, node pools, VPCs, and subnets. In Shared VPC environments, grant VPC and subnet read permissions in the host project. Grant `roles/container.admin` in the service project, and `roles/compute.networkViewer` in the project that owns the network.                                                                                                                                                                                        |
| Data bucket management                     | Service project                                               | The console creates managed data buckets based on instance configuration, or discovers and validates existing data buckets. Recommended role for managed bucket mode: `roles/storage.admin`; existing bucket mode usually requires `roles/storage.bucketViewer`.                                                                                                                                                                                                                    |
| Cloud DNS management                       | Service project; also host project in Shared VPC environments | The console creates or reads Cloud DNS private managed zones, and maintains zone IAM policies in managed DNS mode. Managed DNS mode requires `roles/dns.admin` and creates a custom role named `automqConsoleDnsZoneIamPolicyAdmin`, which contains `dns.managedZones.getIamPolicy` and `dns.managedZones.setIamPolicy`. In Shared VPC environments, the host project also needs `roles/dns.admin` for private zone binding. Existing DNS mode usually requires `roles/dns.reader`. |
| Instance Google Service Account management | Service project                                               | The console creates the instance Google Service Account and configures instance-level IAM bindings in managed identity mode. In existing identity mode, the console reads the target Google Service Account. Managed identity mode requires `roles/iam.serviceAccountAdmin`, `roles/iam.roleAdmin`, and `roles/resourcemanager.projectIamAdmin`; existing identity mode usually requires `roles/iam.serviceAccountViewer`.                                                          |

After granting the permissions, return to the AutoMQ console and click the verification or initialization action. After verification succeeds, you can enter the AutoMQ console and continue configuring GKE.

## Next steps

* **Deploy to GKE**: After installing the console and completing permission initialization, see [Deploy to Google Cloud GKE](/automq-cloud/deploy-automq-on-kubernetes/deploy-to-google-cloud-gke).
* **Use AutoMQ via WebUI**: Continue to create instances through the environment console and experience the product features. [Experience AutoMQ▸](/automq-cloud/getting-started/experience-automq)
* **Use AutoMQ via Terraform**: After installing the console, you can manage and use AutoMQ through the AutoMQ Terraform Provider. For Terraform usage, see the [Terraform Provider documentation](https://registry.terraform.io/providers/AutoMQ/automq/latest/docs).