Skip to main content

Onboard GCP organization to VRM

Users can onboard all projects in the organization to VRM using organization-level onboarding. The following steps outline how to perform organization-level onboarding in VRM.

For the organization integration, the onboarding scripts generate the API key. Once the organization integration is configured, VRM automatically provisions individual project integrations for each GCP project under the associated organization.

Download the onboarding script​

You can download the onboarding script using either of the following methods.

Download from VRM​

The onboarding script can be downloaded via the VRM UI.

To complete this task:

  1. In VRM, from the left navigation menu, select the Settings icon settings_icon.png, and then select Add Connector.
  2. Select Google Cloud Platform.
  3. Select DOWNLOAD SHELL SCRIPT. The VRM GCP onboarding script is downloaded.

The onboarding script is publicly hosted in an Amazon S3 bucket. You can download the onboarding script using one of the following links:

Review requirements and actions of the onboarding script​

Before running the onboarding script, review its parameters, required permissions, and the resources and access it creates.

Review the actions performed by the script​

The script performs the following actions.

  • Creates a new project. If the project already exists, the script uses the existing project.
  • Creates a service account in the project. If a service account with the same name exists, the script uses the existing account.
  • Creates a custom role with the required permissions. If a role with the same ID exists, the permissions mentioned in the script are added to the role.
  • Assigns the custom role to the service account at the organization level.
  • Creates a credential file for the service account. If a file with the same name exists, you can choose to skip creating a new file or create a new file with the date and time appended to the file name to differentiate it from the existing one.

Review the parameters of the script​

The onboarding script has a section where the parameters are listed. The user is advised to fill in the following parameters and review them carefully before proceeding.

  • Required parameter: you must provide the following mandatory parameter.

    • YOUR_ORG_ID: the organization ID you want to onboard into VRM.

  • Optional parameters: these parameters have default values. You can modify them as needed.

    • VRM_PROJECT_NAME: the name of the project the script will create. This project is required to create the service account and generate credentials.
    • VRM_PROJECT_ID: the ID of the project specified above.
    • SERVICE_ACCOUNT_NAME: the name of the service account the script will create. This account is required to generate credentials for ingestion into VRM.
    • VRM_ROLE_ID: the ID of the custom role the script will create. This role grants organization-level permissions that allow VRM to ingest assets and findings from the cloud platform.
    • SERVICE_ACCOUNT_KEY_NAME: the name of the key file generated at the end of the script. You must share this file with VRM to complete the onboarding process.
    • LOG_FILE: the name of the log file. The script writes logs to this file to assist with troubleshooting.

Review the required user permissions​

The user must have the following permissions to run the script successfully. You can also verify if you have the required permissions.

  • resourcemanager.projects.create
  • resourcemanager.projects.get
  • serviceusage.services.enable
  • iam.serviceAccounts.create
  • iam.serviceAccounts.get
  • iam.roles.get
  • iam.roles.create
  • iam.roles.update
  • resourcemanager.projects.setIamPolicy
  • iam.serviceAccountKeys.create

Verify the user permissions​

If you have a role such as Owner, you likely have most or all of the required permissions. You can verify your permissions in Google Cloud.

Update the onboarding script parameters​

Before you run the script in the Cloud Terminal, update the parameters as needed. Do not modify any part of the script other than the parameters unless you fully understand the impact of those changes. There are two types of parameters.

  • Mandatory parameter: you must add the following parameters to the script before running it.

  • Optional parameters: you can modify the following parameters if needed. Default values are already set in the script.

    • VRM_PROJECT_NAME - The name of the project VRM will create.

    • VRM_PROJECT_ID - The ID of the project VRM will create.

      Project naming rules:

      1. Must be globally unique.
      2. Must be between 6 and 30 characters in length.
      3. Can contain only lowercase alphabets, numbers, and hyphens.
      4. Must start with an alphabet.
      5. Cannot end with a hyphen.
      6. Cannot reuse a name that is currently in use or was previously used, including deleted projects.

    • SERVICE_ACCOUNT_NAME - Service account name, which will be created by the script

      Service account naming rules:

      1. Must be between 6 and 30 characters.
      2. Can contain lowercase alphanumeric characters and hyphens.

    • VRM_ROLE_ID - The ID of the custom role the script will create. This role includes the permissions required for onboarding and ingesting resources into VRM.

      Role ID naming rules:

      1. Can be up to 64 bytes in length (limit applies to the size of the string, not the number of characters).
      2. Can contain uppercase and lowercase alphanumeric characters, underscores, and periods.
      3. Cannot reuse a role ID within an organization or project.

    • SERVICE_ACCOUNT_KEY_NAME - The name of the credential file the script will generate. You will need to share this file with VRM. If a file with the same name already exists, the script will prompt you to either overwrite it or create a new file with a timestamp appended to the name.

note

Do not change these parameters unless you fully understand the impact. Ensure that all names comply with the listed naming restrictions.

Upload the onboarding script to Google Cloud console terminal​

You can upload the shell script from local machine to the Cloud Shell.

Run the onboarding script in the Google Cloud console terminal​

Option 1: Run script in Google Cloud console (Cloud Shell)​

Cloud Shell runs with your Google user credentials, so it automatically uses your permissions. However, the script will prompt you to authenticate. You can skip this step if you are already authenticated by selecting No at the following prompt from gcloud: You are already authenticated with gcloud when running inside the Cloud Shell and so do not need to run this command. Do you wish to proceed anyway? Do you want to continue (Y/n)?

To complete this task:

  1. Open Google Cloud console.
  2. Launch Cloud Shell from Google Cloud console.
  3. Upload your script using one of the following methods:
  1. (Optional) Make the script executable: bash chmod +x vrm_gcp_onboarding.sh
  2. Run this script ./vrm_gcp_onboarding.sh or run directly with bash
vrm_gcp_onboarding.sh
  1. View the output. The Cloud Shell terminal displays script output and any errors in real time.

Option 2: Run a script using Google Cloud CLI​

To complete this task:

  1. Install gcloud CLI. Download and install the Google Cloud SDK.
  2. Authenticate. Log in with your Google account or service account.
gcloud auth login
  1. Follow steps 3 to 6 here.

Download the service account key file from Google Cloud console​

The service account key file is necessary to connect your project to VRM. You can download it from Google Cloud.

To complete this task:

  1. In the terminal, click More (the three-dot menu).
  2. Select Download from the menu.
  3. Enter the file name (or the file path if the file isn't in the root directory).
  4. Select Download. The service account JSON key file will be downloaded.
note

After you upload the key file to VRM, make sure to delete the file from your local machine.

Share the service account key file with VRM​

There are two ways through which you can share the service account key file.

Upload via VRM UI​

The onboarding script can be uploaded via the VRM UI.

To complete this task:

  1. In VRM, from the left navigation menu, select the Settings icon settings_icon.png, and then select Add Connector.
  2. Select Google Cloud Platform.
  3. Select browse and select the service account key file from the explorer. Alternatively, you can drag and drop the file into the screen.
  4. Select the CLOUD ACCOUNT VALUE.
  5. Select appropriate options to map ASSET VALUE, ASSET ENVIRONMENT, DATA COMPLIANCE and DATA CLASSIFICATION.
  6. Select CONTINUE.

Upload via VRM API​

Once the script has completed its execution, upload the generated file specified by the SERVICE_ACCOUNT_KEY_NAME parameter to VRM to continue the onboarding process. The file name is displayed in the script output. For API, see here.

To complete this task:

  1. Create the integration. Use the Create Integration API to create the integration. In the request body, specify:
  • A name (optional)
  • cloudServiceProvider as GCP The name of the integration will automatically update to the Organization display name after the credentials file is uploaded, even if you provide a name during creation. You can change the integration name later if needed.
note

The integration will initially be in INACTIVE state. The state will be set to ACTIVE after you upload the secrets.

  1. Retrieve the integration ID. After successfully creating the integration, capture the id field from the API response. You will use this id when calling other APIs related to this integration.

Sample Response:

{
"tenantId": "con_pOjUr2ZRJmv0jsij",
"id": "684a9e40bf81fb6dd37bffae",
"name": "GCP-20250529112357-07",
"accountId": null,
"accountName": null,
"organizationId": null,
...
"cloudServiceProvider": "GCP",
"state": "INACTIVE",
...
}
  1. Use the Update AccessInfo (Update Secrets) API to upload the credentials file. Provide the integration ID obtained in step 2.
    • A 200 OK response indicates success.
    • This API does not return a response body.
  2. Once the credentials file is successfully uploaded, the onboarding process is complete. Your project integrations will begin to appear.

After running the onboarding script​

The onboarding script provides the names and IDs of all resources created during the onboarding process. It’s recommended that you record these details. This will help you clean up the resources later if you choose to offboard your Google Cloud organization from VRM. After running the script, you must upload the JSON credentials file to the VRM platform to continue with the onboarding process. Once the file is uploaded, delete the credentials file from your local machine. If you downloaded the key file to your local machine, it’s recommended that you:

To complete this task:

  1. Delete the file.
  2. Clear it from your trash or recycle bin.
  3. Delete the file from Google Cloud console terminal by running the following command: 
     rm <path_to_file>

Scheduled jobs​

A scheduled job runs once per day and performs the following actions:

  • Creates new integrations in VRM for GCP projects created the previous day.
  • Disables integrations for GCP projects deleted the previous day.
  • Re-enables integrations for GCP projects restored after previously being disabled when the projects were scheduled for deletion.
Last updated on