Skip to main content
GCP onboarding process overview

​
Introduction

This documentation provides a comprehensive guide to onboarding a GCP account to Wiv using a script that automates the creation of a service account, the generation of a service account key, and the assignment of predefined roles to the service account at either the organization or project level.

​
Prerequisites

​
1. BigQuery Cloud Billing Data Export

If you don’t have it, please 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:
ScopeRolePurpose
Organizationroles/resourcemanager.organizationAdminList orgs, set org-level IAM
Projectroles/owner or roles/editorCreate resources, enable APIs
Projectroles/iam.serviceAccountAdminCreate service account and keys
Projectroles/serviceusage.serviceUsageAdminEnable APIs
Projectroles/serviceusage.quotaAdminSet BigQuery quota limits
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 the gcloud auth login command. 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
For a detailed mapping and explanation of the required GCP permissions and their usage, please refer to 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

Here’s a sample output for a user who chose to apply permissions at the organization level: 
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.
By following these steps, you can successfully onboard your GCP account to Wiv, allowing for streamlined management and integration of your cloud resources. Complete the integration:
GCP integration completion in Wiv console