Skip to main content

Troubleshooting

This guide provides troubleshooting steps for common issues encountered during GCP organization integration.

Pre-deployment Checklist​

Before attempting to troubleshoot deployment issues, verify the following prerequisites:

  • If the GCP organization was previously connected via older methods, all relevant resources have been destroyed
    • Upwind Cloud Account Credentials have been deleted from the Settings/Credentials page
    • Projects have been revoked from the Inventory/Accounts page
    • Cloud Scanners have been deleted from the Inventory/Upwind Components/Cloud Scanners page
  • Required APIs are enabled for the GCP organization (see API requirements in the integration guide for the complete list and automated enablement script)
  • Deployment is being performed using a GCP organization administrator account
  • Terraform is being deployed from a clean environment (no other files that may affect configuration)
  • Optional Terraform variables (resource_suffix and google_service_account_display_name) are defined if desired

Common Issues & Solutions​

Issue: Permissions errors reported by Terraform​

Possible Causes:

  1. Terraform is not authenticated by gcloud

    Verify that the gcloud CLI is authenticated with the correct GCP organization administrator account. Use the following command to check the current account:

    gcloud auth list

    To authenticate, use:

    gcloud auth login
    gcloud auth application-default login

  2. Google account does not have organization administrator permissions

    Ensure that the Google account used to authenticate with gcloud has the necessary permissions to create service accounts and manage IAM roles within the GCP organization.

Issue: Failure to create resources that already exist​

Possible Causes:

  1. Existing resources from previous integration attempts

If the integration has already been attempted, some resources may already exist. In this case, you can either:

  • Delete the existing resources manually from the GCP console
  • Use the terraform destroy command to remove all resources created by Terraform

If you choose to delete resources manually, ensure that you remove all relevant Upwind resources, including:

  • Service accounts
  • IAM roles and bindings
  • Secret Manager secrets
  • Cloud Scheduler jobs
  • Managed Instance Groups
  • VPC Networks, Subnets, Routers, and Firewall rules

  1. Terraform state file issues

    If the Terraform state file is corrupted or not in sync with the actual resources, you may encounter errors. In this case, you can try:

    • Running terraform refresh to update the state file
    • Manually removing the problematic resources from the state file using terraform state rm <resource_name>

Issue: Google Cloud APIs are not enabled​

If the required APIs are not enabled, you may encounter errors during deployment. The error message will typically indicate which API is missing.

Recommended Solution

Use the automated bash script provided in the prerequisites guide to enable all required APIs across your projects. This script will:

  • Check which APIs are already enabled
  • Enable missing required APIs
  • Provide options for additional API sets (Posture APIs, Cloud Scanner APIs)
  • Handle multiple projects automatically

Manual API Enablement:

To enable a specific API manually, use the following command:

gcloud services enable <api_name> --project=<project_id>

To check the status of all APIs in a specific project, use:

gcloud services list --project=<project_id>

Required APIs:

The complete list of required APIs is available in the prerequisites guide. The mandatory APIs include:

  • Cloud Asset API (cloudasset.googleapis.com)
  • Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
  • Compute Engine API (compute.googleapis.com)
  • IAM Service Account Credentials API (iamcredentials.googleapis.com)
  • Identity and Access Management API (iam.googleapis.com)
  • Kubernetes Engine API (container.googleapis.com)
  • Secret Manager API (secretmanager.googleapis.com)
  • Security Token Service API (sts.googleapis.com)
  • Service Usage API (serviceusage.googleapis.com)

Additional APIs may be required for Cloud Scanners and Posture features. See the integration guide for the complete list.

Issue: WIF configuration file is not uploaded to Upwind​

If the WIF configuration file is not uploaded to Upwind, it signifies that Upwind was unable to authenticate with the GCP organization using the provided credentials. This can occur if:

  • The Workload Identity Federation (WIF) configuration was not generated correctly
  • The WIF configuration file was not uploaded to the Upwind successfully

To resolve this issue, ensure that you have followed the steps to generate the WIF configuration file correctly and uploaded it to Upwind. If you encounter issues during this process, refer to the Workload Identity Federation documentation for guidance on generating and configuring WIF.

On Page Reload

The onboarding page automatically generates a random suffix value for Terraform on each page load. Ensure that the command used to generate the WIF configuration matches the resources created by Terraform.