Troubleshoot a GCP deployment

Find the symptom you see in the tables below, then apply the fix beside it. Each table covers one stage of a qumulo_filesystem_gcp run, or one kind of change to a running cluster.

Fix plan errors

Symptom	Fix
instance_type fails validation	Choose a type from GCP machine types.
Requested capacity exceeds instance capacity	Lower soft_capacity_limit_tb, add nodes, or choose a larger type from GCP machine types.
Invalid availability zone count	Use 1 zone for single-zone or 3 or more for multi-zone.
Zone not in region	List only zones that sit in the cluster's region.
Invalid node_count for multi-zone deployment	Use node_count = 3 or 5 and up, or deploy into a single zone.
Image pair must be set together	Set both node_image_project and node_image_family, or omit both. The provisioner pair follows the same rule.

Fix apply errors

Symptom	Fix
Creation fails early with a "service not enabled" error	Run gcloud services enable compute.googleapis.com storage.googleapis.com iam.googleapis.com --project <PROJECT_ID>, then apply again.
The provisioner hangs	Turn on Private Google Access for the subnetwork under VPC network > Subnets > Edit, so nodes without external IPs can reach Cloud Storage. Then apply again.
Creating the cluster service account fails with a permission error	Grant the deploying principal roles/iam.serviceAccountAdmin, or set service_account_email to an existing account.
Another IAM permission error	Grant the deploying principal the roles in GCP project prerequisites.
The node or provisioner image cannot be read	Grant roles/compute.imageUser on the image or its project to the deploying principal and the cluster service account.

Fix image changes

Symptom	Fix
You removed an image line, and the plan shows no change	Set the field to "" instead. Image fields keep their last applied value when the line is removed.
You set node_image_project and node_image_family, and no nodes were replaced	Also set node_image = "". A pinned node_image wins over the family pair.
You want the default Ubuntu 24.04 LTS image back	Set node_image, node_image_project, and node_image_family to "".
A provisioner image change replaced nothing	No fix needed. The provisioner VM is short-lived, and the next operation that runs it, such as a scale, uses the new image. The same "" rules apply to provisioner_image, provisioner_image_project, and provisioner_image_family.

Fix destroy errors

Symptom	Fix
terraform destroy refuses with Cluster is protected from deletion	Set deletion_protection = false, run terraform apply, then run terraform destroy.

Get more detail

Run TF_LOG=DEBUG terraform apply for the provider's full log.