Integration

Overview

This article outlines the steps to integrate your Google Cloud organization and its projects with Upwind.

Prerequisites

To successfully integrate your Google Cloud organization with Upwind, ensure the following prerequisites are met:

Existing GCP organization. Ensure you have a Google Cloud environment structured under an organization node. This is required for centralized visibility and access control across projects and folders. If you need to create one, refer to the Creating and managing organizations documentation.
Access to the Google Cloud organization. Ensure you have administrator access to your Google Cloud organization, as this is necessary for configuring and managing the integration with Upwind. Ensure gcloud is installed and authenticated with this organization.
```
gcloud auth login
gcloud auth application-default login
```
Terraform Installed. All Upwind related infrastructure will be deployed via Terraform. The minimum required version of Terraform is 1.5.7.

Google Cloud APIs & Services. Ensure the following APIs are enabled in your Google Cloud project. For more information on how to do this, refer to the Enable and Disable APIs guide.

Mandatory APIs for Operational Use

Title	Name
Cloud Asset API	`cloudasset.googleapis.com`
Cloud Resource Manager API	`cloudresourcemanager.googleapis.com`
Compute Engine API	`compute.googleapis.com`
Identity and Access Management API	`iam.googleapis.com`
Kubernetes Engine API	`container.googleapis.com`

Mandatory APIs for Posture

Title	Name
Access Approval API	`accessapproval.googleapis.com`
Admin SDK Directory API	`admin.googleapis.com`
AlloyDB Admin API	`alloydb.googleapis.com`
API Keys API	`apikeys.googleapis.com`
BigQuery API	`bigquery.googleapis.com`
Cloud Dataproc API	`dataproc.googleapis.com`
Cloud DNS API	`dns.googleapis.com`
Cloud Functions API	`cloudfunctions.googleapis.com`
Cloud Key Management Service API	`cloudkms.googleapis.com`
Cloud Logging API	`logging.googleapis.com`
Cloud Monitoring API	`monitoring.googleapis.com`
Cloud Redis API	`redis.googleapis.com`
Cloud SQL Admin API	`sqladmin.googleapis.com`
Cloud Storage API	`storage.googleapis.com`
Essential Contacts API	`essentialcontacts.googleapis.com`
Service Usage API	`serviceusage.googleapis.com`

Mandatory APIs for Cloud Scanners

Title	Name
Secret Manager API	`secretmanager.googleapis.com`
Identity and Access Management API	`iam.googleapis.com`
IAM Service Account Credentials API	`iamcredentials.googleapis.com`
Compute Engine API	`compute.googleapis.com`
Cloud Run Admin API	`run.googleapis.com`
Cloud Scheduler API	`cloudscheduler.googleapis.com`
Cloud Resource Manager API	`cloudresourcemanager.googleapis.com`
Kubernetes Engine API	`container.googleapis.com`

Integration steps

Summary

The integration of the Google Cloud Organization consists of three steps:

Step 1: Selecting the Google Cloud Organization and an Orchestrator project.
Step 2: Deploying the Terraform module to create the necessary resources.
Step 3: Generating a Workload Identity Federation (WIF) configuration to allow Upwind to access your Google Cloud Organization and its projects.
Step 4: Defining which projects you want Upwind to scan.

Log in to the Upwind Management Console .
Select the + (plus) symbol at the top of the screen and select Connect cloud account.
Choose Google Cloud Platform, and from there Connect Google Cloud Organization.

note

The Terraform module does not attempt to manage or directly interact with multiple projects within the Google Cloud Organization. Instead, it follows a simplified approach where the same module can be applied to each project individually to create the necessary resources.

It is assumed that the module will be used within other Infrastructure-as-Code (IaC) tools capable of handling deployments at scale across multiple projects, and can be more easily integrated into your team’s workflows.

Step 1: Onboard your Google Cloud Organization and designate an Orchestrator Project

In this step, you will provide key identifiers from your Google Cloud environment and register them in the Upwind Management Console.

Step 1.1: Provide the parameters to identify your Google Cloud Organization

Sign in to the Google Cloud Console using an account with organization-level access.
Navigate to IAM & Admin → Settings.
Copy your Organization ID – this is the unique identifier for your Google Cloud organization.
Paste the Organization ID into the field labeled "Enter Google Cloud Organization ID".

Designate an Orchestrator Project

Enter the Project ID you want to designate as the Orchestrator Project. This project will be responsible for deploying and managing Cloud Scanner resources on behalf of your organization.
The orchestrator project should have sufficient permissions to interact with organization-level resources and initiate scans across projects.

note
The Orchestrator Project must belong to the same GCP Organization and be granted the necessary permissions (via service account) to access and scan other projects.
This does not have to be the organization’s billing or parent project.

Step 1.2: Generate Credentials for Upwind

In this step, you will generate the client credentials that allow the Upwind Orchestrator Project to authenticate with the Upwind Authorization Service and interact with Upwind APIs.
These credentials are required to connect your GCP organization to Upwind and enable secure reporting and scanning.

You will generate two sets of credentials:

GoogleCloudOrgConnectionCredentials - used to authenticate and identify projects within your Google Cloud organization.
These credentials are essential for allowing Upwind to discover, connect, and onboard your Google Cloud projects.
GoogleCloudScannersReportingCredentials - used to securely report scan results from your Google Cloud projects back to Upwind.
They enable continuous visibility by allowing Upwind to receive findings, metadata, and status updates from your scanned resources.

Click "Generate new client credentials" to create both sets of credentials. Once generated, they will be used in later steps to complete the onboarding process.

Step 2: Deploy the Terraform module to provision the necessary resources

In this step, you’ll provision the necessary resources to enable Upwind to access and scan your Google Cloud projects.

The module will deploy all required resources and configure authentication via Workload Identity Federation. This will grant access to your GCP environment specifically from Upwind's AWS environment.

This will then allow Upwind to automatically deploy the Cloud Scanner infrastructure – including required components like IAM roles and compute resources – ensuring full and continuous scanning coverage across your environment.

note

All required parameters have already been injected into the Terraform module for you – no manual input is needed.

Step 2.1: Assign the required Google roles

Before proceeding, review all the settings and parameters to ensure the configuration settings are tailored to your environment.
Create a new directory for your Terraform project and navigate to it in your terminal. Inside the project directory.
Create a new file named main.tf to hold the Terraform configuration.

Copy the code snippet from the Terraform setup section and paste it into main.tf.

main.tf
module "upwind_integration_gcp_onboarding" {
  source = "upwindsecurity/onboarding/google//modules/organization"

  # (Optional) Specify the version of the module to use
  # version = "~> x.y.z"

  # Upwind Details
  upwind_organization_id = "your-upwind-organization-id"

  # Upwind Credentials
  upwind_client_id     = "your-unique-upwind-client-id"
  upwind_client_secret = "your-unique-upwind-client-secret"

  # Cloud Scanner Credentials
  scanner_client_id     = "your-unique-upwind-scanner-id"
  scanner_client_secret = "your-unique-upwind-scanner-secret"

  # GCP Details
  gcp_organization_id = "your-gcp-organization-id"

  # GCP Project to act as the orchestrator
  upwind_orchestrator_project = "orchestrator-project-name"

  # Enable or disable Cloud Scanners
  enable_cloudscanners = true

  # (Optional) Define a custom service account display name
  google_service_account_display_name = "Upwind Service Account"

  # (Optional) Define a custom resource suffix for the Upwind resources
  # This is limited to 10 characters and must be alphanumeric
  resource_suffix = "upwind"
}

Default Module Parameters
`project`	Ensure the parameter is set with the Google Cloud project ID used for provisioning. This is required in the provider block to target the correct GCP project.
`upwind_organization_id`	Ensure the parameter is set with your Upwind Organization ID. This ID typically starts with `org_` and uniquely identifies your organization in the Upwind platform.
`upwind_client_id`	Ensure the parameter is set with the `GoogleCloudOrgConnectionCredentials` client ID generated in the previous step.
`upwind_client_secret`	Ensure the parameter is set with the `GoogleCloudOrgConnectionCredentials` client secret generated in the previous step. Must be used in conjunction with Upwind Client ID.
`scanner_client_id`	Ensure the parameter is set with the `GoogleCloudScannersReportingCredentials` client ID generated in the previous step.
`scanner_client_secret`	Ensure the parameter is set with the `GoogleCloudScannersReportingCredentials` client secret generated in the previous step. Must be used in conjunction with Upwind Client ID.
`gcp_organization_id`	Ensure the parameter is set with your GCP Organization ID, typically a numeric string that uniquely identifies your Google Cloud environment.
`upwind_orchestrator_project`	Ensure the parameter is set with the Google Cloud project ID designated to act as the orchestrator. This project will host the Upwind service account and coordinate scanning operations.
`enable_cloudscanners`	Ensure the parameter is set to `true` if you want to enable deployment of Cloud Scanner infrastructure for continuous scanning of GCP projects.
`google_service_account_display_name` (Optional)	Ensure the parameter is set if you wish to define a custom display name for the Upwind service account in GCP.
`resource_suffix` (Optional)	Ensure the parameter is set with a short, alphanumeric string (max 10 characters) if you want to customize the suffix used in Upwind resource naming to prevent naming collisions.

Step 2.2: Terraform apply

The module can be run manually using terraform init && terraform apply, however, it was designed with the expectation that it will be integrated into an Infrastructure-as-Code (IaC) tool such as Terragrunt or a CI/CD pipeline.
This makes it easier to deploy the module consistently across multiple GCP projects within your organization.

Once the terraform apply command has successfully executed, the connection should be established within a few moments. Detected projects will be listed in the next section.

Step 3: Generate Workload Identity Federation (WIF) configuration

In this step, you will generate the Workload Identity Federation (WIF) configuration that allows Upwind to securely access your Google Cloud Organization and its projects. This configuration is essential for enabling Upwind to authenticate and interact with your GCP resources without needing to manage long-lived credentials.

To configure WIF via gcloud, you will need to run the following command in your terminal:

gcloud iam workload-identity-pools create-cred-config \                                                                                                                                        upwindsecurity-xa  10:58:24
  <PROVIDER> \
  --service-account=<SERVICE_ACCOUNT> \
  --service-account-token-lifetime-seconds=3600 \
  --enable-imdsv2 \
  --aws \
  --output-file=wif.json

Replace <PROVIDER> with the full path of the GCP WIF Pool Provider generated during terraform apply, e.g.

projects/665770712641/locations/global/workloadIdentityPools/upwind-cc7a2-pool-20250617-0842/providers/upwind-cc7a2-aws-provider

# WORKLOAD_IDENTITY_POOL_PROJECT is the project ID where the WIF pool was created, e.g. `upwindsecurity-xa`
gcloud iam workload-identity-pools list --location=global --project=<WORKLOAD_IDENTITY_POOL_PROJECT>
# POOL is the full path of the WIF pool, e.g. `projects/665770712641/locations/global/workloadIdentityPools/upwind-cc7a2-pool-20250617-0842`
gcloud iam workload-identity-pools providers list --location=global --workload-identity-pool=<POOL>

note

It is important that the Pool name contains the project ID as a number, not as a string. Terraform may output this as a string, so ensure you convert it to a number if necessary.

Replace <SERVICE_ACCOUNT> with the service account email address generated during terraform apply, e.g. upwind-mgmt-cc7a2-ycptwgku@upwindsecurity-xa.iam.gserviceaccount.com
If desired, adjust the --service-account-token-lifetime-seconds to set a different token lifetime (default is 3600 seconds).

Upload the generated WIF configuration file to Upwind in the Workload Identity Federation section of the Google Cloud Organization onboarding page.

Step 4: Define Project Scope

The final step of the onboarding process allows you to define the scope for each GCP project you’ve just connected — as well as for any new projects that may be created in the future.

This view displays your organization structure and connected projects, allowing you to choose which projects should be audited using Cloud APIs or scanned using Upwind Cloud Scanners.
- Enable Cloud API to grant general access to the Upwind API.
- Enable Cloud Scanner to deploy the Upwind Cloud Scanner in the selected project.
  
  Scope Dependency
  Cloud Scanner scopes are dependent on the Cloud API scope. If you enable the Cloud Scanner scope, the Cloud API scope must also be enabled.
Enable Auto-Connect for New Projects - when enabled, all newly created projects under the organization will be automatically connected to Upwind. These projects will be granted Cloud API access and scanned by the Cloud Scanner by default, ensuring continuous visibility and protection without further setup.
Test Connectivity by clicking the Test & Save button. This will store the scope settings and check the connection between Upwind and the GCP organization. If successful, you will see a success message.

You're now fully connected to Upwind and protected across the selected Google Cloud projects.

Unsupported Regions

Some regions are not yet supported for Upwind Cloud Scanner deployments, as Google Cloud Run Scheduler is not available:

asia-northeast3
asia-south2
australia-southeast2
europe-north1
europe-southwest1
europe-west10
europe-west12
europe-west4
europe-west8
europe-west9
me-central1
me-central2
me-west1
northamerica-northeast1
northamerica-northeast2
northamerica-south1
us-east5
us-south1

Troubleshooting

If you encounter issues during deployment or operation, consult the Troubleshooting guide for solutions and best practices.

Overview​

Prerequisites​

Integration steps​

Step 1: Onboard your Google Cloud Organization and designate an Orchestrator Project​

Step 1.1: Provide the parameters to identify your Google Cloud Organization​

Designate an Orchestrator Project​

Step 1.2: Generate Credentials for Upwind​

Step 2: Deploy the Terraform module to provision the necessary resources​

Step 2.1: Assign the required Google roles​

Step 2.2: Terraform apply​

Step 3: Generate Workload Identity Federation (WIF) configuration​

Step 4: Define Project Scope​

Unsupported Regions​

Troubleshooting​

Overview

Prerequisites

Integration steps

Step 1: Onboard your Google Cloud Organization and designate an Orchestrator Project

Step 1.1: Provide the parameters to identify your Google Cloud Organization

Designate an Orchestrator Project

Step 1.2: Generate Credentials for Upwind

Step 2: Deploy the Terraform module to provision the necessary resources

Step 2.1: Assign the required Google roles

Step 2.2: Terraform apply

Step 3: Generate Workload Identity Federation (WIF) configuration

Step 4: Define Project Scope

Unsupported Regions

Troubleshooting