Importing GCP Organization to SaaS Workspace

In this guide, you will:

• Learn how to import an entire Google Cloud Platform (GCP) Organization into Turbot Guardrails in SaaS environment. This process allows Guardrails to discover and manage resources across all projects and folders under a single GCP Organization.
• Monitor and troubleshoot the process.

Importing a GCP Organization into Guardrails involves these key steps:

• Configuring a GCP Service Account with appropriate permissions at the organization level.
• Importing the organization via the Guardrails console.

Prerequisites

• Access to the Guardrails console with Turbot/Owner or Turbot/Admin permissions at the Turbot resource level.
• Minimum Turbot Enterprise (TE) version v5.48.0 or later.
• GCP mod 5.30+ installed in your Guardrails workspace.
• GCP Console: Familiarity with the GCP Console, including admin privileges.
• The gcloud CLI configured on your local environment.

Supported Authentication

Guardrails supports two credential methods to import a GCP Organization:

• Service Account Impersonation: Grants temporary credentials using GCP Service account impersonation.
• JSON Credential File: Uses a downloaded JSON key file or requires copying and pasting the private_key section of the JSON file.

Note

We recommend Service Account Impersonation, as it eliminates the need to download or manage a JSON key, reducing security risks. This guide demonstrates Service Account Impersonation.

If you prefer to use the JSON Credential File, refer to the steps mentioned in Connect a GCP Project in the Getting Started with GCP guide.

Step 1: Enable Required APIs

Guardrails requires access to the Cloud Resource Manager and Service Management APIs to discover and manage organization-wide resources. Refer the GCP documentation to enable the APIs using Console and gcloud.

Refer to the image below as example using as example in GCP Console.

Step 2: Create Service Account

To import an organization into Guardrails, create the service account in any single project under your organization. Prepare a GCP Project for Import to Guardrails. The step Locate IAM & Admin > Service Accounts elaborates the steps to create service account.

Step 3: Grant IAM Roles

Tip

In GCP, service accounts are always associated with a specific project, even if their permissions are applied at the project, folder, or organization level.

Required Permissions

The table below outlines the minimum permissions required for organization-wide governance on service account:

Follow these steps to assign the required roles at the Organization scope to the service account:

• Navigate to IAM & Admin > IAM in the Google Cloud console.
• Select your Organization from the resource selector.
• Select Grant Access.
• Enter the Principal as SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com, that you created part of previous step.
• Assign the required roles at the organization (or folder) scope as described in Required Permissions on Service Account.

Refer to the image below:

Note

To import an organization, you need only Organization Viewer, Project Viewer, and Folder Viewer roles to allow the discovery of all resources under the organization.

Alternatively you can grant roles using gcloud command line interface as below.

#  Create the service account in a specific project
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME --project=PROJECT_ID --description="Service account for Guardrails"
# Assign roles at the organization level
gcloud organizations add-iam-policy-binding ORGANIZATION_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="ROLE_NAME"

Step 4: Get Organization ID

In the GCP console, select your organization. Navigate to All to view the list of projects, folders, and the organization itself. Locate and copy the ID of the organization.

Step 5: Import Organization into Guardrails

Log into the Guardrails console with provided local credentials or by using any SAML based login and select the CONNECT card.

Select GCP and then choose the GCP Organization option.

• Choose the folder where the GCP organization will be imported.

• Choose one of the Access modes from the provided list. In this guide, Service Account impersonation is demonstrated.

• Provide the Organization ID for your GCP organization and the Client email. Guardrails will use this email ID for impersonation.

Proceed for setting up Service Account Impersonation.

Step 6: Setup Service Account Impersonation

• The impersonating user or service account (i.e. the identity that runs Guardrails) must have the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on the target service account.

• The target service account just created for organization importing purpose i.e. the one being impersonated must have the required organization-level permissions as as described in What Permissions to Grant to discover or manage resources across your GCP Organization.

In the same page, select Copy gcloud command.

Now execute copied command using gcloud CLI in your local environment.

# Replace SERVICE_ACCOUNT_NAME and PROJECT_ID with your service account's name/project
# Replace IMPERSONATOR_EMAIL with the user or service account that will impersonate it

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:IMPERSONATOR_EMAIL" --role="roles/iam.serv

Validate the output.

⇒ gcloud iam service-accounts add-iam-policy-binding mrk-sa-test@mrk-sandbox.iam.gserviceaccount.com --member=serviceAccount:integration-gcp@turbot-guardrails-dev.iam.gserviceaccount.com --role=roles/iam.serviceAccountTokenCreator --format=json
Updated IAM policy for serviceAccount [mrk-sa-test@mrk-sandbox.iam.gserviceaccount.com].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:integration-gcp@turbot-guardrails-dev.iam.gserviceaccount.com"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwYsqn0-odQ=",
  "version": 1
}

Step 7: Create External ID Label

The External ID label acts as a key service account identifier within the project that your service account belongs to. Create a label with the key guardrails_external_id and value: turbot_162167737252865_f1da2779-92c8-46b1-83dd-95d629023211. This value is randomly populated by Guardrails.

Note

The Label key and the highlighted portion of the value (i.e., turbot_162167737252865 in the format turbot_{current workspace id}) cannot be modified. However, the third part of the text can be customized by clicking the Customize icon.

Log in to the GCP console and navigate to the project where the configured service account resides. Select Labels from the side navigation panel, add guardrails_external_id as the label key, and turbot_162167737252865_f1da2779-92c8-46b1-83dd-95d629023211 as the value. Click +Add label to save the label.

Warning

The External ID label created in the GCP project for the organization import must be retained within the respective GCP project to prevent errors in Guardrails.

Step 8: Exclude Projects

This step is required if you wish to exclude specific projects or folder under organization from being imported into Guardrails.

Important

Existing projects already connected individually in Guardrails will automatically move under the organization hierarchy. If you do not wish to move them, list them in the YAML exclusion list.

Click the Edit button to provide a list of project IDs or folder names under the organization to be excluded.

Click the Preview button to ensure no errors are displayed. Move to Step 14.

Step 9: Start Import

Click Connect to begin the import process.

Guardrails will create and execute discovery controls for your GCP Organization, scanning each folder, project and resources under it.

Review

• Confirm that the organization CMDB and discovery controls are in the OK state.

Navigate to the Resources tab, search for the organization name, then select Controls tab besides to check the controls are on OK state.

• Verify that the projects and folders are successfully imported into Guardrails and match the GCP console.

Navigate to the Resources tab, search for the organization name to check the list of resources the import process is discovered matching to the structure in GCP console.

Next Steps

• Learn how to Enable GCP Services in Guardrail.
• Learn how to Configure Real-Time Event Handlers.

Troubleshooting