Set up Google Cloud Storage

You can also use Workload Identity Federation (WIF) pools with Google Cloud Storage.

Unlike with application credentials, WIF allows you to use temporary credentials. Each time you make a request to GCS, Label Studio connects to your identity pool to request temporary credentials.

For more information about WIF, see Google Cloud - Workload Identity Federation.

Before you begin:

• Review the information in Cloud storage for projects and Secure access to cloud storage.
• Configure access to your bucket.

Service account permissions

You will need a service account that has the following permissions

• Bucket: Storage Admin (roles/storage.admin)
• Project: Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
• Project: Storage Object Viewer (roles/storage.viewer)

See Create service accounts in the Google Cloud documentation.

Create a Workload Identity Pool

There are several methods you can use to create a WIF pool.

terraform init
terraform plan
terraform apply

## Variables
/* AWS variables are so that AWS-hosted Label Studio resources can reach out to request credentials */

variable "gcp_project_name" {
  type        = string
  description = "GCP Project name"
}

variable "gcp_region" {
  type        = string
  description = "GCP Region"
}

variable "label_studio_gcp_sa_name" {
  type        = string
  description = "GCP Label Studio Service Account Name"
}

variable "aws_account_id" {
  type        = string
  description = "AWS Project ID"
}

variable "aws_role_name" {
  type        = string
  description = "AWS Role name"
}

variable "external_ids" {
  type        = list(string)
  default = []
  description = "List of external ids"
}

## Outputs

output "GCP_WORKLOAD_ID" {
  value = google_iam_workload_identity_pool_provider.label-studio-provider-jwt.workload_identity_pool_id
}

output "GCP_WORKLOAD_PROVIDER" {
  value = google_iam_workload_identity_pool_provider.label-studio-provider-jwt.workload_identity_pool_provider_id
}

## Main

provider "google" {
  project = var.gcp_project_name
  region  = var.gcp_region
}

resource "random_id" "random" {
  byte_length = 4
}

locals {
  aws_assumed_role = "arn:aws:sts::${var.aws_account_id}:assumed-role/${var.aws_role_name}"

  external_id_condition = (
    length(var.external_ids) > 0
    ? format("(attribute.aws_role == \"%s\") && (attribute.external_id in [%s])",
      local.aws_assumed_role,
      join(", ", formatlist("\"%s\"", var.external_ids))
    )
    : format("(attribute.aws_role == \"%s\")", local.aws_assumed_role)
  )
}

resource "google_iam_workload_identity_pool" "label-studio-pool" {
  workload_identity_pool_id = "label-studio-pool-${random_id.random.hex}"
  project                   = var.gcp_project_name
}

resource "google_iam_workload_identity_pool_provider" "label-studio-provider-jwt" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.label-studio-pool.workload_identity_pool_id
  workload_identity_pool_provider_id = "label-studio-jwt-${random_id.random.hex}"

  attribute_condition = local.external_id_condition

  attribute_mapping = {
    "google.subject"        = "assertion.arn"
    "attribute.aws_account" = "assertion.account"
    "attribute.aws_role"    = "assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn"
    "attribute.external_id" = "assertion.external_id"
  }

  aws {
    account_id = var.aws_account_id
  }
}

data "google_service_account" "existing_sa" {
  account_id = var.label_studio_gcp_sa_name
}

resource "google_service_account_iam_binding" "label-studio-sa-oidc" {
  service_account_id = data.google_service_account.existing_sa.name
  role               = "roles/iam.workloadIdentityUser"

  members = [
    "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.label-studio-pool.name}/attribute.aws_role/${local.aws_assumed_role}"
  ]
}

Create a source storage connection

From Label Studio, open your project and select Settings > Cloud Storage > Add Source Storage.

Select Google Cloud Storage (WIF Auth) and click Next.

Configure Connection

Complete the following fields and then click Test connection:

Import Settings & Preview

Complete the following fields and then click Load preview to ensure you are syncing the correct data:

Review & Confirm

If everything looks correct, click Save & Sync to sync immediately, or click Save to save your settings and sync later.

Create a target storage connection

From Label Studio, open your project and select Settings > Cloud Storage > Add Target Storage.

Select Google Cloud Storage (WIF Auth) and click Next.

Complete the following fields:

After adding the storage, click Sync.

Google Cloud Storage service account impersonation allows a Google Cloud service account to temporarily assume the permissions of another service account without requiring access to its keys.

When deploying Label Studio on Google Kubernetes Engine (GKE), workloads typically authenticate using a Kubernetes service account mapped to a Google Cloud service account through Workload Identity. However, this directly linked GCP service account might not have broad access to your GCS buckets.

With service account impersonation, the workload’s GCP service account can instead impersonate a separate, more privileged service account that has the necessary storage permissions. This approach eliminates the need to create, distribute, and rotate long-lived service account keys, reducing the risk of credential leakage.

For more information, see:

• Service account impersonation
• Use service account impersonation

Before you begin:

• Review the information in Cloud storage for projects and Secure access to cloud storage.
• Configure access to your bucket.
• You will need the base service account email from your Label Studio platform administrator. This is the GCP service account that is bound to the Kubernetes service account running Label Studio via GKE Workload Identity. If this has not been set up yet, see Configure the GKE project (platform administrator) below.

You will be working in two Google Cloud projects:

• Your base GKE project. This is where you have deployed Label Studio using GKE.
• Your target Google Cloud project. This is where your GCS buckets are located.

Configure the GKE project (platform administrator)

This is a one-time setup performed by the platform administrator who manages the Label Studio deployment in GKE. If this has already been completed, you can skip to Configure the target Google Cloud project and request the base service account email from your administrator.

Enable the feature flag

You must enable the fflag_feat_bros_763_gcs_sa_impersonation feature flag in your Label Studio deployment in order to use service account impersonation. You can add this under extraEnvironmentVars in your helm chart:

global:
  extraEnvironmentVars:
      fflag_feat_bros_763_gcs_sa_impersonation: "true"

Create a base service account

Create a GCP service account in the GKE project that will serve as the identity for your Label Studio pods. This is the “base” service account that will later be granted permission to impersonate target service accounts in other projects.

1. From the Google Cloud Console, ensure you are in the GKE project (the project where Label Studio is deployed).
2. Go to IAM & Admin > Service Accounts.
3. Click Create Service Account.
4. Enter a name and description (for example, lse-base).
5. Click Done. No additional roles need to be granted at this stage.
6. Note the service account email (for example, lse-base@your-gke-project.iam.gserviceaccount.com). This is the base service account email that you will share with data teams who need to configure bucket access.

Bind the base service account to the Kubernetes service account

Use GKE Workload Identity to link the GCP base service account to the Kubernetes service account used by your Label Studio pods. This allows the pods to automatically authenticate as the base service account without managing keys.

1. Add the Workload Identity annotation to the Kubernetes service account used by Label Studio:

   kubectl annotate serviceaccount label-studio-sa \
     --namespace=label-studio \
     iam.gke.io/gcp-service-account=BASE_SA_EMAIL

   Replace label-studio-sa and label-studio with your actual Kubernetes service account name and namespace, and BASE_SA_EMAIL with the email from the previous step.

2. Grant the Workload Identity User role so the Kubernetes service account can act as the GCP service account:

   gcloud iam service-accounts add-iam-policy-binding BASE_SA_EMAIL \
     --role="roles/iam.workloadIdentityUser" \
     --member="serviceAccount:GKE_PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

   Where:

   • BASE_SA_EMAIL is the base service account email (for example, lse-base@your-gke-project.iam.gserviceaccount.com).
   • GKE_PROJECT_ID is the ID of your GKE project.
   • NAMESPACE is the Kubernetes namespace where Label Studio is deployed (for example, label-studio).
   • KSA_NAME is the name of the Kubernetes service account used by Label Studio (for example, label-studio-sa).

3. Verify the binding is working by running a test pod:

   kubectl run workload-identity-test \
     --image=google/cloud-sdk:slim \
     --serviceaccount=label-studio-sa \
     --namespace=label-studio \
     -it --rm -- gcloud auth list

   The output should show the base service account email as the active account.

For more information, see Use Workload Identity in the Google Cloud documentation.

resource "google_service_account" "lse_base" {
  project      = "your-gke-project"
  account_id   = "lse-base"
  display_name = "Label Studio Base SA"
}

resource "google_service_account_iam_member" "workload_identity_binding" {
  service_account_id = google_service_account.lse_base.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "serviceAccount:your-gke-project.svc.id.goog[label-studio/label-studio-sa]"
}

Configure the target Google Cloud project

Step 1: Create a service account in your target Google Cloud project

In your Google Cloud project where your bucket is located, create a service account that Label Studio will impersonate to access your data.

1. From the Google Cloud Console, go to IAM & Admin > Service Accounts.
2. Click Create Service Account.
3. Enter a name and description (for example, sa-label-studio-data).
4. Click Create and Continue.
5. Note the service account email (for example, sa-label-studio-data@your-data-project.iam.gserviceaccount.com). You will need this later.

See Create service accounts in the Google Cloud documentation.

Step 2: Grant the target service account access to your bucket

Grant the target service account the appropriate roles on the Google Cloud Storage bucket that you want to connect to Label Studio. The roles you need depend on how you plan to use the storage:

• For source storage (importing data): roles/storage.objectViewer
• For target storage (exporting annotations): roles/storage.objectAdmin

roles/storage.objectAdmin is required for target storage because Label Studio needs to create, overwrite, and optionally delete objects in the bucket. If you only need write access without deletion, roles/storage.objectCreator is sufficient, but the Can delete objects from storage option will not work.

1. Go to Cloud Storage > Buckets and select your bucket.
2. Click Permissions and then click Grant Access.
3. In the New principals field, enter the target service account email you received in step 1.
4. In the Role dropdown, select Storage Object Viewer (roles/storage.objectViewer) for source storage or Storage Object Admin (roles/storage.objectAdmin) for target storage. Use Add another role to add both if needed.
5. Click Save.

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \
  --member="serviceAccount:TARGET_SA_EMAIL" \
  --role="roles/storage.objectViewer"

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \
  --member="serviceAccount:TARGET_SA_EMAIL" \
  --role="roles/storage.objectAdmin"

Step 3: Allow impersonation from the Label Studio base service account

This step authorizes the Label Studio base service account (running in GKE) to impersonate your target service account.

Grant roles/iam.serviceAccountTokenCreator to the base service account on the target service account. This role also includes the signBlob permission, which Label Studio uses to generate pre-signed URLs for direct browser access to stored objects.

1. Go to IAM & Admin > Service Accounts and select the target service account you created in step 1.
2. Click the Permissions tab and then click Grant Access.
3. In the New principals field, enter the base service account email provided by your Label Studio platform administrator in the base account.
4. In the Role dropdown, select Service Account Token Creator (roles/iam.serviceAccountTokenCreator).
5. Click Save.

gcloud iam service-accounts add-iam-policy-binding TARGET_SA_EMAIL \
  --member="serviceAccount:BASE_SA_EMAIL" \
  --role="roles/iam.serviceAccountTokenCreator"

Step 4: Configure CORS on the bucket (required for pre-signed URLs)

If you plan to use pre-signed URLs (the default), you must configure Cross-Origin Resource Sharing (CORS) on your GCS bucket so that the annotator’s browser can load media files directly from Google Cloud Storage.

1. Create a file called cors.json with the following content:

   [
     {
       "origin": ["https://your-label-studio-domain.com"],
       "method": ["GET", "HEAD"],
       "responseHeader": ["Content-Type", "Content-Range", "Content-Disposition"],
       "maxAgeSeconds": 3600
     }
   ]

   Replace https://your-label-studio-domain.com with the URL where your Label Studio instance is accessible.

2. Apply the CORS configuration to the bucket:

   gcloud storage buckets update gs://YOUR_BUCKET_NAME --cors-file=cors.json

3. Verify the CORS configuration:

   gcloud storage buckets describe gs://YOUR_BUCKET_NAME --format="default(cors_config)"

If you are using Proxy through the platform mode instead of pre-signed URLs, CORS configuration is not required because all traffic flows through the Label Studio server.

Create a source storage connection

From Label Studio, open your project and select Settings > Cloud Storage > Add Source Storage.

Select Google Cloud Storage (SA Impersonation) and click Next.

Configure Connection

Complete the following fields and then click Test connection:

Import Settings & Preview

Complete the following fields and then click Load preview to ensure you are syncing the correct data:

Review & Confirm

If everything looks correct, click Save & Sync to sync immediately, or click Save to save your settings and sync later.

Create a target storage connection

From Label Studio, open your project and select Settings > Cloud Storage > Add Target Storage.

Select Google Cloud Storage (SA Impersonation) and click Next.

Complete the following fields:

After adding the storage, click Sync.

Troubleshooting