Set up Google Cloud Storage

echo '[
   {
      "origin": ["*"],
      "method": ["GET"],
      "responseHeader": ["Content-Type","Access-Control-Allow-Origin"],
      "maxAgeSeconds": 3600
   }
]' > cors-config.json

gsutil cors set cors-config.json gs://YOUR_BUCKET_NAME

  For more information, see
  <a href="storage#Pre-signed-URLs-vs-Storage-proxies">Pre-signed URLs vs Storage proxies</a>.
</td>

  export GOOGLE_APPLICATION_CREDENTIALS=json-file-with-GCP-creds-23441-8f8sd99vsd115a.json

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}"
  ]
}

Where:

* `[POOL_ID]` is the ID that you want to assign to your WIF pool (for example, `label-studio-pool-abc123`). Note this because you will need to reuse it later. 
* `[PROJECT_ID]` is the ID of your Google Cloud project. 
* `[POOL_DISPLAY_NAME]` is a human-readable name for your pool (optional, but recommended).

1. Create the provider for AWS.

 This allows AWS principals that have the correct external ID and AWS role configured to impersonate the Google Cloud service account. This is necessary because the Label Studio resources making the request are hosted in AWS. 

 ```shell
 gcloud iam workload-identity-pools providers create-aws [PROVIDER_ID] \
 --workload-identity-pool="[POOL_ID]" \
 --account-id="490065312183" \
 --attribute-condition="attribute.aws_role==\"arn:aws:sts::490065312183:assumed-role/label-studio-app-production\"" \
 --attribute-mapping="google.subject=assertion.arn,attribute.aws_account=assertion.account,attribute.aws_role=assertion.arn,attribute.external_id=assertion.external_id"

 ```
 Where: 

 * `[PROVIDER_ID]` is a provider ID (for example, `label-studio-app-production`).  
 * `[POOL_ID]`: The pool ID you provided in step 1. 

2. Grant the [service account](#Service-account-permissions) that you created earlier the `iam.workloadIdentityUser` role.

 ```shell
 gcloud iam service-accounts add-iam-policy-binding [SERVICE_ACCOUNT_EMAIL] \
 --role="roles/iam.workloadIdentityUser" \
 --member="principalSet://iam.googleapis.com/projects/[PROJECT_NUMBER]/locations/global/workloadIdentityPools/[POOL_ID]/attribute.aws_role/arn:aws:sts::490065312183:assumed-role/label-studio-app-production"
 ```

 Where: 

 * `[SERVICE_ACCOUNT_EMAIL]` is the email associated with you GCS service account (for example, `my-service-account@[PROJECT_ID].iam.gserviceaccount.com`).
 * `[PROJECT_NUMBER]`: Your Google project number. This is different than the project ID. You can find the project number with the following command:

     `gcloud projects describe $PROJECT_ID --format="value(projectNumber)"`
 * `[POOL_ID]`: The pool ID you provided in step 1. 

Before setting up your connection in Label Studio, note what you provided for the following variables (you will be asked to provide them):

* `[POOL_ID]` 
* `[PROVIDER_ID]` 
* `[SERVICE_ACCOUNT_EMAIL]`
* `[PROJECT_NUMBER]`
* `[PROJECT_ID]` 

</details>

<details>
<summary>Using the Google Cloud Console</summary>



Before you begin, ensure you are in the correct project:

![Screenshot of the GCS console with project highlighted](/images/storages/gcs-project.png)

1. From the Google Cloud Console, navigate to [**IAM & Admin > Workload Identity Pools**](https://console.cloud.google.com/iam-admin/workload-identity-pools). 

2. Click **Get Started** to enable the APIs. 

3. Under **Create an identity pool**, complete the following fields: 

 * **Name**: This is the pool ID (for example, `label-studio-pool-abc123`). Note this ID because you will need it again later. 
 * **Description**: This is the display name for the pool (for example, "Label Studio Pool"). 

4. Under **Add a provider pool**, complete the following fields:

 * **Select a provider**: Select AWS. This is the location where the Label Studio components responsible for issuing requests are stored. 
 * **Provider name**: Enter `Label Studio App Production` (you can use a different display name, but you need to ensure that the corresponding provider ID is still `label-studio-app-production`)
 * **Provider ID**: Enter `label-studio-app-production`.
 * **AWS Account ID**: Enter `490065312183`.

5. Under **Configure provider attributes**, enter the following: 

 * Click **Add condition** and then enter the following: 

     `attribute.aws_role=="arn:aws:sts::490065312183:assumed-role/label-studio-app-production"`

 * Click **Edit mapping** and then add the following: 

     - `google.subject = assertion.arn`
     - `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` (this might be filled in by default)
     - `attribute.aws_account = assertion.account`
     - `attribute.external_id = assertion.external_id`

6. Click **Save**. 

7. Go to **IAM & Admin > Service Accounts** and find the service account you want to allow AWS (Label Studio) to impersonate. See [Service account permissions](#Service-account-permissions) above. 

8. From the **Principals with access** tab, click **Grant Access**. 

 ![Screenshot of grant access button](/images/storages/gcs-grant-access.png)

9. In the **New principals** field, add the following:

 `principalSet://iam.googleapis.com/projects/[PROJECT_NUMBER]/locations/global/workloadIdentityPools/[POOL_ID]/attribute.aws_role/arn:aws:sts::490065312183:assumed-role/label-studio-app-production`

 Where:

 * `[PROJECT_NUMBER]` - Replace this with your Google project number. This is different than the project ID. To find the project number, go to **IAM & Admin > Settings**.
 * `[POOL_ID]` - Replace this with the pool ID (the **Name** you entered in step 3 above, e.g. `label-studio-pool-abc123`).

9. Under **Assign Roles**, use the search field in the **Role** drop-down menu to find the **Workload Identity User** role. 

 ![Screenshot of principal window](/images/storages/gcs-principal.png)

10. Click **Save**

Before setting up your connection in Label Studio, note the following (you will be asked to provide them)

* Your pool ID - available from **IAM & Admin > Workload Identity Pools** 
* Your provider ID - available from **IAM & Admin > Workload Identity Pools** (this should be `label-studio-app-production`)
* Your service account email - available from **IAM & Admin > Service Accounts**. Select the service account and the email is listed under **Details**.  
* Your Google project number - available from **IAM & Admin > Settings**
* Your Google project ID - available from **IAM & Admin > Settings**

</details>

### 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**:


<div class="noheader rowheader">

<table style="width: 100%; border-collapse: collapse;">
<tr>
 <th style="width: 25%;">Field</th>
 <th>Description</th>
</tr>

<tr>
 <td>Storage Title</td>
 <td>Enter a name to identify the storage connection.</td>
</tr>

<tr>
 <td>Bucket Name</td>
 <td>
   Enter the name of your GCS bucket.
 </td>
</tr>

<tr>
 <td>Workload Identity Pool ID</td>
 <td>
   This is the ID you specified when creating the Work Identity Pool. You can find this in Google Cloud Console under <strong>IAM & Admin > Workload Identity Pools</strong>. 
 </td>
</tr>

<tr>
 <td>Workload Identity Provider ID</td>
 <td>
   This is the ID you specified when setting up the provider. You can find this in Google Cloud Console under <strong>IAM & Admin > Workload Identity Pools</strong>.
 </td>
</tr>

<tr>
 <td>Service Account Email</td>
 <td>
   This is the email associated with the service account you set up as part of the prerequisites. You can find it in the <strong>Details</strong> page of the service account under <strong>IAM & Admin > Service Accounts</strong>. For example, <code>[email protected]</code>.
 </td>
</tr>

<tr>
 <td>Google Project ID</td>
 <td>
   Your Google project ID. You can find this in Google Cloud Console under <strong>IAM & Admin > Settings</strong>.
 </td>
</tr>

<tr>
 <td>Google Project Number</td>
 <td>
   Your Google project number. You can find this in Google Cloud Console under <strong>IAM & Admin > Settings</strong>. 
 </td>
</tr>

<tr>
 <td>Use pre-signed URLs (On) /
Proxy through the platform (Off)</td>
 <td>
   This determines how data from your bucket is loaded:
   <ul>
     <li><strong>Use pre-signed URLs</strong>: Label Studio generates time-limited HTTPS links directly to your S3/GCS/Azure objects and redirects the browser there (HTTP 303), so annotators' browsers download media straight from cloud storage. This is usually faster and scales better, but requires correct CORS and presign permissions on the bucket. It also means traffic flows from browser to storage, not through Label Studio.</li>
     <li><strong>Proxy through the platform</strong> – The backend downloads the file from cloud storage and streams it to the browser, so all media traffic passes through the Label Studio server. This keeps data fully inside the Label Studio/network boundary, enforces task-level access checks on every request, and avoids CORS/presign setup, but uses more Label Studio worker resources and can be slightly slower.</li>
   </ul>
   

   For more information, see
   <a href="storage#Pre-signed-URLs-vs-Storage-proxies">Pre-signed URLs vs Storage proxies</a>.
 </td>
</tr>

<tr>
 <td>Expire pre-signed URLs (minutes)</td>
 <td>Control how long pre-signed URLs remain valid.</td>
</tr>

</table>
</div>

#### Import Settings & Preview

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

<div class="noheader rowheader">

| | |
| --- | --- |
| Bucket Prefix | Optionally, enter the directory name within your bucket that you would like to use.  For example, `data-set-1` or `data-set-1/subfolder-2`.  | 
| Import Method | Select whether you want create a task for each file in your bucket or whether you would like to use a JSON/JSONL/Parquet file to define the data for each task. |
| File Name Filter | Specify a regular expression to filter bucket objects. Use `.*` to collect all objects. |
| Scan all sub-folders | Enable this option to perform a recursive scan across subfolders within your container. |

</div>

#### Review & Confirm

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


!!! info Tip
 You can also use the API to [sync import storage](https://api.labelstud.io/api-reference/api-reference/import-storage/gcswif/sync).



### 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:

<div class="noheader rowheader">

<table style="width: 100%; border-collapse: collapse;">

<tr>
 <td style="width: 25%;">Storage Title</td>
 <td>Enter a name to identify the storage connection.</td>
</tr>

<tr>
 <td>Bucket Name</td>
 <td>
   Enter the name of your GCS bucket.
 </td>
</tr>

<tr>
 <td>Bucket Prefix</td>
 <td>
   Optionally, enter the directory name within your bucket that you would like to use.  For example, <code>data-set-1</code> or <code>data-set-1/subfolder-2</code>. 
 </td>
</tr>

<tr>
 <td>Workload Identity Pool ID</td>
 <td>
   This is the ID you specified when creating the Work Identity Pool. You can find this in Google Cloud Console under <strong>IAM & Admin > Workload Identity Pools</strong>. 
 </td>
</tr>

<tr>
 <td>Workload Identity Provider ID</td>
 <td>
   This is the ID you specified when setting up the provider. You can find this in Google Cloud Console under <strong>IAM & Admin > Workload Identity Pools</strong>.
 </td>
</tr>

<tr>
 <td>Service Account Email</td>
 <td>
   This is the email associated with the service account you set up as part of the prerequisites. You can find it in the <strong>Details</strong> page of the service account under <strong>IAM & Admin > Service Accounts</strong>. For example, <code>[email protected]</code>.
 </td>
</tr>

<tr>
 <td>Google Project ID</td>
 <td>
   Your Google project ID. You can find this in Google Cloud Console under <strong>IAM & Admin > Settings</strong>.
 </td>
</tr>

<tr>
 <td>Google Project Number</td>
 <td>
   Your Google project number. You can find this in Google Cloud Console under <strong>IAM & Admin > Settings</strong>. 
 </td>
</tr>

<tr>
 <td>Can delete objects from storage</td>
 <td>Enable this option if you want to delete annotations stored in the bucket when they are deleted in Label Studio. Your credentials must include the ability to delete bucket objects.</td>
</tr>

</table>
</div>

After adding the storage, click **Sync**. 

!!! info Tip
 You can also use the API to [sync export storage](https://api.labelstud.io/api-reference/api-reference/export-storage/gcswif/sync).

</div>


## Add storage with the Label Studio API

You can also use the API to programmatically create connections. [See our API documentation.](https://api.labelstud.io/api-reference/introduction/getting-started)


## IP filtering for enhanced security for GCS

Google Cloud Storage offers [bucket IP filtering](https://cloud.google.com/storage/docs/ip-filtering-overview) as a powerful security mechanism to restrict access to your data based on source IP addresses. This feature helps prevent unauthorized access and provides fine-grained control over who can interact with your storage buckets.

Read more about [Source storage behind your VPC](security.html#Source-storage-behind-your-VPC).

**Common Use Cases:**
- Restrict bucket access to only your organization's IP ranges
- Allow access only from specific VPC networks in your infrastructure
- Secure sensitive data by limiting access to known IP addresses
- Control access for third-party integrations by whitelisting their IPs

<details>
<summary>How to Set Up IP Filtering</summary>



1. First, create your GCS bucket through the console or CLI
2. Create a JSON configuration file to define IP filtering rules. You have two options:
For public IP ranges:
```json
{
"mode": "Enabled", 
"publicNetworkSource": {
 "allowedIpCidrRanges": [
   "xxx.xxx.xxx.xxx", // Your first IP address
   "xxx.xxx.xxx.xxx", // Your second IP address
   "xxx.xxx.xxx.xxx/xx" // Your IP range in CIDR notation
 ]
}
}

{
  "mode": "Enabled",
  "vpcNetworkSources": [
    {
      "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
      "allowedIpCidrRanges": [
        RANGE_CIDR
      ]
    }
  ]
}

gcloud alpha storage buckets update gs://BUCKET_NAME --ip-filter-file=IP_FILTER_CONFIG_FILE

gcloud alpha storage buckets update gs://BUCKET_NAME --clear-ip-filter