Prerequisites

Before you begin to onboard your Google Cloud Platform (GCP) environment to Cortex, ensure that:

1. Ensure you have the necessary permissions:

   • In Cortex, you must have a Cortex role with Data Sources - View & Edit permissions (to add/configure cloud accounts in Cortex). This role is included in the following built-in roles: Instance Administrator, Security Admin, and IT Admin.
   • In GCP, you must have an admin user with the required GCP permissions.
2. Enable the necessary APIs in the GCP project you are onboarding.
3. You identify and set your target project.
4. Decide on your resource naming convention. Throughout this manual onboarding process, you will need to choose your own names for service accounts, custom roles, and Pub/Sub topics. Use the Configuration values reference to keep track of the names as you will need to refer to them throughout the process.

P.1 Grant required admin GCP permissions for Cortex onboarding

Use the following template to create a dedicated role with the permissions required for onboarding GCP to Cortex:

{
"title": "CortexCloudOnboarding",
"description": "Custom role with permissions required for onboarding Cortex Cloud",
"stage": "GA",
"includedPermissions": [
    "iam.roles.create",
    "iam.roles.delete",
    "iam.roles.get",
    "iam.roles.list",
    "iam.roles.update",
    "iam.serviceAccounts.create",
    "iam.serviceAccounts.delete",
    "iam.serviceAccounts.get",
    "iam.serviceAccounts.getIamPolicy",
    "iam.serviceAccounts.list",
    "iam.serviceAccounts.setIamPolicy",
    "iam.serviceAccounts.update",
    "logging.sinks.create",
    "logging.sinks.delete",
    "logging.sinks.get",
    "logging.sinks.update",
    "pubsub.subscriptions.create",
    "pubsub.subscriptions.delete",
    "pubsub.subscriptions.getIamPolicy",
    "pubsub.subscriptions.setIamPolicy",
    "pubsub.subscriptions.update",
    "pubsub.topics.create",
    "pubsub.topics.delete",
    "pubsub.topics.getIamPolicy",
    "pubsub.topics.setIamPolicy",
    "pubsub.topics.update",
    "resourcemanager.folders.get",
    "resourcemanager.folders.getIamPolicy",
    "resourcemanager.folders.list",
    "resourcemanager.folders.setIamPolicy",
    "resourcemanager.organizations.get",
    "resourcemanager.organizations.getIamPolicy",
    "resourcemanager.organizations.setIamPolicy",
    "resourcemanager.projects.get",
    "resourcemanager.projects.getIamPolicy",
    "resourcemanager.projects.list",
    "resourcemanager.projects.setIamPolicy"
    ]
}

To create a custom role with these permissions in the GCP host project, run the following in Cloud Shell:

gcloud iam roles create <ROLE_ID> \
  --project=<HOST_PROJECT_ID> \
  --file=<JSON_FILE_PATH>

Where:

• <ROLE_ID> is your chosen name for the role
• <HOST_PROJECT_ID> is the GCP host project ID where service accounts are created
• <JSON_FILE_PATH> is the file path and file name of the JSON file containing the permissions template

To grant the custom role to the user performing the onboarding, run the following in Cloud Shell:

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="user:<USER_EMAIL>" \
  --role="<ROLE_ID>"

Where:

• <PROJECT_ID> is the ID of the GCP project you are onboarding to Cortex
• <USER_EMAIL> is the email address of the user who will be performing the onboarding
• <ROLE_ID> is the role ID from the custom role you created

P.2 Enable necessary APIs in GCP

Ensure that the following APIs are enabled in the GCP project you are onboarding. You can enable them using the gcloud CLI.

API name	Service name (for CLI)	Required?
Cloud Resource Manager API	cloudresourcemanager.googleapis.com	Required
Identity and Access Management (IAM) API	iam.googleapis.com	Required
Cloud Pub/Sub API	pubsub.googleapis.com	Required if audit log collection will be enabled
Kubernetes Engine API	container.googleapis.com	Required if automation will be enabled as an additional security capability
Compute Engine API	compute.googleapis.com	Required if automation will be enabled as an additional security capability
Service Usage API	serviceusage.googleapis.com	Required if automation will be enabled as an additional security capability
Cloud Storage API	storage-api.googleapis.com	Required if automation will be enabled as an additional security capability

P.2.1 Enable APIs using Cloud Shell

To enable an API, run the following command in your terminal:

gcloud services enable <SERVICE_NAME> --project=<HOST_PROJECT_ID>

Where:

• <SERVICE_NAME> is the name of the service you want to enable
• <HOST_PROJECT_ID> is your GCP host project ID (where service accounts are created)

You can enable multiple services at once by passing all services names in a single command:

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com pubsub.googleapis.com container.googleapis.com compute.googleapis.com serviceusage.googleapis.com storage-api.googleapis.com \
  --project=<HOST_PROJECT_ID>

P.3 Identify and set your host project

1. Identify your target scope and retain the ID numbers as they will be required throughout the onboarding process.

   • <HOST_PROJECT_ID>: The GCP host project ID (where service accounts are created)
   • <FOLDER_ID>: The numeric ID of the folder to onboard
   • <ORG_ID>: The numeric ID of the organization the folder belongs to
2. Set your host project. Your host project is where service accounts are created. In Google Cloud Shell or your local terminal, run:

gcloud config set project <HOST_PROJECT_ID>

where <HOST_PROJECT_ID> is the GCP host project ID where service accounts are created.