GCP Onboarding Process (Manual)

Prefer keyless onboarding (no JSON keys)? Use the in-app wizard in GCP Onboarding Process.

This guide uses a Cloud Shell script that creates a service account, generates a service account key, and assigns predefined roles at organization or project scope. You then upload key.json in Wiv.

Prerequisites

1. BigQuery Cloud Billing Data Export

If you don't have it, follow this guide. Choose Detailed usage cost data.

2. Required Permissions

The user running this script needs the following permissions:

For Standalone Project setup:

• resourcemanager.projects.create (or use an existing project)
• serviceusage.services.enable on the target project
• iam.serviceAccounts.create on the target project
• iam.serviceAccounts.keys.create on the target project
• resourcemanager.projects.setIamPolicy on the target project
• serviceusage.quotas.update on the target project (for BigQuery quota limits)

For Organization-wide setup (additional permissions):

• resourcemanager.organizations.get
• resourcemanager.organizations.getIamPolicy
• resourcemanager.organizations.setIamPolicy

Recommended predefined roles:

If you don't have organization-level permissions, the script will automatically fall back to standalone project mode.

Step-by-step guide

1. Login to GCP

Open GCP Cloud Shell with the onboarding repo: https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/wiv-ai/GCPOnBoarding.git

2. Run the script

Start the script by executing:

./GCPWivOnBoarding.sh

3. Login to GCP

The script will prompt you to log in to Google Cloud using gcloud auth login. Follow the instructions in your terminal to authenticate.

4. Select configuration type

The script will ask if you want to set up for a standalone project or an entire organization:

Is this for a standalone project or an entire organization? 1) Standalone Project 2) Entire Organization

Standalone Project: Permissions will be set at the project level. Entire Organization: If you choose to set permissions at the organization level, the script will fetch a list of organizations available to you. If there are multiple organizations, you will be prompted to select one.

5. Enter the project ID for service account creation

The script will prompt you for a GCP Project ID where the service account will be created:

Enter the project ID to create the service account wiv-sa (usually project that contains the billing dataset):

Enter the project ID, for example, my-gcp-project.

6. API enablement

The script will enable the following APIs on the specified project:

• recommender.googleapis.com
• cloudresourcemanager.googleapis.com
• compute.googleapis.com

These APIs are necessary for the service account's intended permissions. If they are already enabled, the script will inform you.

7. Service account creation

The script creates a new service account named wiv-sa with the display name "Wiv Service Account."

8. Generate service account key

The script will generate a key for the service account and save it as key.json in the current directory. This key file is essential for applications or scripts that need to authenticate as the service account.

9. Assign IAM roles

The script will assign the following IAM roles to the service account at either the organization or project level:

• roles/recommender.computeViewer
• roles/recommender.viewer
• roles/monitoring.viewer
• roles/compute.viewer
• roles/bigquery.jobUser
• roles/recommender.bigQueryCapacityCommitmentsViewer
• roles/container.viewer
• roles/bigquery.dataViewer
• roles/cloudsql.viewer
• roles/run.viewer
• roles/cloudfunctions.viewer
• roles/pubsub.viewer
• roles/spanner.viewer
• roles/logging.viewer
• roles/iam.securityReviewer
• roles/compute.networkViewer
• roles/cloudbuild.builds.viewer
• roles/dataflow.viewer
• roles/redis.viewer
• roles/securitycenter.viewer
• roles/cloudkms.viewer
• roles/artifactregistry.reader
• roles/gkebackup.viewer
• roles/cloudasset.viewer
• roles/bigquery.resourceViewer
• roles/billing.viewer

For a detailed mapping and explanation of the required GCP permissions and their usage, see the GCP Permissions List.

10. Completion

After the script finishes running, you'll see a completion message confirming that the service account has been created and configured:

=== Onboarding Complete === Service account wiv-sa@PROJECT_ID.iam.gserviceaccount.com has been created and configured. All necessary permissions have been granted at [organization/project] level for TARGET_ID. Key file has been saved as key.json in the current directory. === Configuration Summary === Service Account Project: PROJECT_ID Key File Name: key.json

Verify permissions

After running the script, verify that the service account has been created and the roles have been assigned correctly in the GCP Console IAM & Admin section.

Additional notes

• Error handling: If any step fails, the script will print an error message indicating the issue and exit. Check the error message to identify what needs to be corrected (e.g., insufficient permissions or an incorrect project ID).
• Security: Keep key.json secure as it contains sensitive information. You may want to move it to a safe location or restrict its permissions after the script completes.

Example output

Is this for a standalone project or an entire organization? 1) Standalone Project 2) Entire Organization #? 2 Multiple organizations found. Please choose one: 1) Org1 2) Org2 #? 1 Enter the project ID to create the service account wiv-sa (usually project that contains the billing dataset): my-gcp-project recommender.googleapis.com is already enabled on project my-gcp-project. cloudresourcemanager.googleapis.com is already enabled on project my-gcp-project. compute.googleapis.com is already enabled on project my-gcp-project. Created service account [wiv-sa]. Service account key has been exported to the current directory. IAM policy bindings added successfully at organization level (123456789012). === Onboarding Complete === Service account wiv-sa@my-gcp-project.iam.gserviceaccount.com has been created and configured. All necessary permissions have been granted at organization level for 123456789012. Key file has been saved as key.json in the current directory. === Configuration Summary === Service Account Project: my-gcp-project Key File Name: key.json

Ensure that you have the necessary permissions and understand the implications of assigning roles at the organization level. Misconfigurations can lead to security risks or unintended access to resources within your organization. Always follow the principle of least privilege when assigning roles.

Complete the integration in Wiv

1. Sign in to Wiv and go to Integrations → GCP.
2. Click New GCP Integration, then Onboard Manually (or open the GCP instance form directly).
3. Enter an integration name and upload key.json.
4. Enter the billing export Billing Project ID, Billing Dataset Name, and Billing Table Name.
5. Click Save.