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:
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:
Copy
./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:
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, 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
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
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
