GCP Environment Initialization

This guide covers everything you need to initialize a Fractal Cloud environment on Google Cloud Platform.

Prerequisites

We recommend that an administrator performs environment initialization, as the GCP principal will need privileged access.

An administrator may group the needed permissions into a "Bootstrap Admin" custom role to allow a group of principals to perform environment initialization independently. See Roles and permissions for details.

Organization-level permission required (Shared VPC)

Fractal Cloud uses a Shared VPC network model on GCP: the management project is enabled as the Shared VPC host, and every operational project is attached to it as a service project.

Enabling a host project and attaching service projects requires the compute.organizations.enableXpnHost permission, which is organization-scoped — it cannot be granted at the project level. The initializing principal must be granted Compute Shared VPC Admin (roles/compute.xpnAdmin) at the organization (or folder) level.

ORG_ID="your-org-id"   # gcloud organizations list

gcloud organizations add-iam-policy-binding "$ORG_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/compute.xpnAdmin

If this is missing, initialization fails with:

Status(StatusCode="PermissionDenied", Detail="Required 'compute.organizations.enableXpnHost' permission for 'projects/<project>'")

The error names the project, but the permission is checked at the organization. Granting it requires roles/resourcemanager.organizationAdmin — typically only your GCP org administrator can perform this binding.

Initialize via Web UI

No additional configuration is required beyond having the necessary IAM permissions on your GCP project. Follow the general Web UI steps to complete the initialization.

Initialize via SDK

Step 1: Create a service account

PROJECT_ID="your-project-id"

# Create the service account
gcloud iam service-accounts create fractal-cloud-initializer \
  --display-name "Fractal Cloud Initializer" \
  --project "$PROJECT_ID"

SERVICE_ACCOUNT="fractal-cloud-initializer@${PROJECT_ID}.iam.gserviceaccount.com"

Step 2: Assign required roles

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/editor \
  --project "$PROJECT_ID"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/compute.networkAdmin \
  --project "$PROJECT_ID"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/serviceusage.serviceUsageAdmin \
  --project "$PROJECT_ID"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/resourcemanager.projectIamAdmin \
  --project "$PROJECT_ID"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/secretmanager.admin \
  --project "$PROJECT_ID"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/run.admin \
  --project "$PROJECT_ID"

The roles above are project-scoped. The Shared VPC host/service-project wiring additionally requires an organization-scoped role (see the Shared VPC caution under Prerequisites):

ORG_ID="your-org-id"   # gcloud organizations list

gcloud organizations add-iam-policy-binding "$ORG_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/compute.xpnAdmin

Step 3: Create a JSON key file

gcloud iam service-accounts keys create fractal-cloud-initializer-key.json \
  --iam-account="$SERVICE_ACCOUNT" \
  --project "$PROJECT_ID"

Important

Make sure the Service Usage API is enabled for your project. The initialization process will automatically enable additional required APIs.

gcloud services enable serviceusage.googleapis.com --project "$PROJECT_ID"

Step 4: Set environment variables

The SDK authenticates using the following environment variables:

Variable	Description
GCP_SERVICE_ACCOUNT_EMAIL	Email of the GCP service account ($SERVICE_ACCOUNT)
GCP_SERVICE_ACCOUNT_CREDENTIALS	Base64-encoded service account key JSON

Important

The Fractal SDK requires the service account key as a base64-encoded JSON string:

cat fractal-cloud-initializer-key.json | base64

Step 5: Run the initialization

Follow the environment initialization sample to initialize the environment programmatically.