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.

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"

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.