Hybrid VPC — Google Cloud Storage

This guide covers setting up Hybrid VPC with Google Cloud Storage (GCS) as your storage backend. Reducto writes documents, results, and intermediate artifacts to a GCS bucket in your GCP project and signs in as a service account that you create.

How access works

Reducto authenticates with a JSON key for a service account in your project. Reducto never falls back to its own Google identity: a GCS environment without a key is rejected when you save it.
The key is not tied to a Reducto region, so GCS setup needs no Reducto principal ARNs, ExternalId, or per-region trust configuration. One key works for US, EU, and AU processing.
Keyless access (Workload Identity Federation or service account impersonation) is not supported for GCS.
After you save the key, Reducto never returns it. The configuration API and audit log show service_account_json_configured: true instead.

Prerequisites

GCP project that owns the bucket, with permission to create buckets, service accounts, and service account keys
Service account key creation allowed in that project (see the warning in step 4)
Owner or Admin role in your Reducto organization, to configure Hybrid VPC in Studio
gcloud CLI (optional, for the commands below)

Setup

Create the bucket

Choose a location in the data residency where Reducto should process your documents (see Data residency).

gcloud storage buckets create gs://acme-reducto-data \
  --project=acme-prod \
  --location=us-central1 \
  --uniform-bucket-level-access \
  --public-access-prevention

GCS bucket names must not start with goog or contain google.

Create a service account

gcloud iam service-accounts create reducto-hybrid-vpc \
  --project=acme-prod \
  --display-name="Reducto Hybrid VPC"

Use a dedicated service account for Reducto, with no other roles.

Grant the service account access to the bucket

Grant both roles on the bucket only, not on the project:

SA="reducto-hybrid-vpc@acme-prod.iam.gserviceaccount.com"

gcloud storage buckets add-iam-policy-binding gs://acme-reducto-data \
  --member="serviceAccount:$SA" --role="roles/storage.objectAdmin"

gcloud storage buckets add-iam-policy-binding gs://acme-reducto-data \
  --member="serviceAccount:$SA" --role="roles/storage.legacyBucketReader"

Role	Why Reducto needs it
`roles/storage.objectAdmin`	Read input documents, write results and artifacts, and delete temporary objects
`roles/storage.legacyBucketReader`	Read bucket metadata (`storage.buckets.get`). Verification checks the bucket before it tests object access

Signing result URLs needs no extra role: Reducto signs them with the key itself, not through the IAM signBlob API.

Create a JSON key

gcloud iam service-accounts keys create reducto-key.json \
  --iam-account="reducto-hybrid-vpc@acme-prod.iam.gserviceaccount.com"

Many GCP organizations enforce the iam.disableServiceAccountKeyCreation organization policy, which blocks this command. Ask your GCP organization admin for an exception on the project that holds the Reducto service account. Reducto cannot connect to GCS without a key.

Add a lifecycle rule (recommended)

Delete Reducto objects automatically one day after they are created. See Data lifecycle.

Configure the environment in Studio

In Studio, go to Settings → Hybrid VPC.
Add a new environment and choose Google Cloud Storage as the provider.
Enter the region, bucket name, project ID, and optional bucket folder (see Integration values).
Paste the full contents of reducto-key.json into service_account_json.
Click Verify storage access. Reducto reads the bucket metadata, then writes, reads, and deletes a test object named .reducto-hybrid-vpc-verify.txt in the bucket folder.
Save the configuration after verification succeeds.

After you save, delete your local copy of reducto-key.json or move it to your secret manager.If you do not see the Hybrid VPC tab, ask Reducto to turn on self-serve Hybrid VPC for your organization, or send the integration values to your Reducto team through a secure channel.

If your Reducto team manages your organization’s Hybrid VPC environment profile, ask them to make changes. A Reducto-managed profile takes precedence over environments saved in Studio.

Integration values

Value	Description
`storage_type`	`gcs`
`region`	GCP region of the bucket, for example `us-central1`, `europe-west1`, or `australia-southeast1`. Reducto uses it only to choose the data residency
`bucket`	GCS bucket name, without `gs://`
`project_id`	ID of the GCP project that owns the bucket (6–30 lowercase letters, numbers, or hyphens). Use the project ID, not the project number
`bucket_folder`	Optional object prefix for everything Reducto writes, for example `reducto/`. Must not start with `/` or contain `..`
`service_account_json`	Required. The full JSON key of the service account from step 4

GCS-only configurations do not need an external_id. That value applies only to S3 environments.

Data residency

The region decides which Reducto region processes the environment’s documents. Send requests for the environment to the matching API endpoint:

`region` starts with	Residency	API endpoint
`us-`, `northamerica-`	US	`https://platform.reducto.ai`
`europe-`	EU	`https://eu.platform.reducto.ai`
`australia-`	AU	`https://au.platform.reducto.ai`

Other GCP regions, such as asia-* or southamerica-*, are not supported. For a multi-region or dual-region bucket (for example location US or EU), enter a region in the same residency, such as us-central1 or europe-west1. Reducto does not check the region against the bucket’s location. A request sent to an endpoint whose residency does not match the environment’s region fails with HTTP 400.

Multiple environments

You can add several GCS environments, and mix them with S3 environments, under one Reducto organization, for example staging, prod, staging-gcp, and prod-gcp. Each environment has its own bucket, service account key, and region. A saved configuration applies to all Reducto regions. The Hybrid VPC configuration has this shape:

{
  "default_environment": "prod-gcp",
  "environments": {
    "prod-gcp": {
      "storage_type": "gcs",
      "region": "us-central1",
      "bucket": "acme-reducto-data",
      "project_id": "acme-prod",
      "bucket_folder": "reducto/",
      "service_account_json": { "type": "service_account", "...": "..." }
    },
    "staging-gcp": {
      "storage_type": "gcs",
      "region": "us-central1",
      "bucket": "acme-reducto-staging",
      "project_id": "acme-staging",
      "service_account_json": { "type": "service_account", "...": "..." }
    }
  }
}

Environment names use 1–80 letters, numbers, underscores, periods, or hyphens. A request without an environment uses default_environment. When the organization has more than one environment, set a default or name an environment on every request. Without a default, a request that names no environment either fails or, if Reducto also registered regional S3 storage for your organization, writes to that S3 storage instead of GCS.

Usage

Select the environment per request. Where the setting goes depends on the endpoint:

/parse: settings.hybrid_vpc.environment
/extract and /split: parsing.settings.hybrid_vpc.environment

/extract and /split ignore a top-level settings.hybrid_vpc. The request then runs on your default environment instead of the one you named, without an error.

You can pass a gs://bucket/object-key URI as the input. Reducto downloads it with the environment’s service account, so the object can stay private. The URI names its own bucket and key, so bucket_folder does not apply to it. To read from a bucket other than the Reducto bucket, grant the service account roles/storage.objectViewer on that bucket. If you configure the recommended lifecycle rule, keep source documents that you want to retain outside the Reducto bucket folder.

Reducto reads a gs:// input only with the credentials of the GCS environment selected for the request. If your default environment is S3, name the GCS environment in the request.

from reducto import Reducto

client = Reducto()  # Reads REDUCTO_API_KEY from the environment

result = client.parse.run(
    input="gs://acme-reducto-data/documents/contract.pdf",
    settings={"hybrid_vpc": {"environment": "prod-gcp"}},
)

from reducto import Reducto

client = Reducto()

result = client.extract.run(
    input="gs://acme-reducto-data/documents/contract.pdf",
    instructions={"schema": {"type": "object", "properties": {"party": {"type": "string"}}}},
    parsing={"settings": {"hybrid_vpc": {"environment": "prod-gcp"}}},
)

import Reducto from "reductoai";

const client = new Reducto(); // Reads REDUCTO_API_KEY from the environment

const parsed = await client.parse.run({
  input: "gs://acme-reducto-data/documents/contract.pdf",
  settings: { hybrid_vpc: { environment: "prod-gcp" } },
});

const extracted = await client.extract.run({
  input: "gs://acme-reducto-data/documents/contract.pdf",
  instructions: { schema: { type: "object", properties: { party: { type: "string" } } } },
  parsing: { settings: { hybrid_vpc: { environment: "prod-gcp" } } },
});

curl -X POST "https://platform.reducto.ai/parse" \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "gs://acme-reducto-data/documents/contract.pdf",
    "settings": {"hybrid_vpc": {"environment": "prod-gcp"}}
  }'

Result URLs

URLs in responses, such as large results and images, are V4 signed GET URLs on storage.googleapis.com for one object in your bucket. They expire after 12 hours. The application that opens them must be able to reach storage.googleapis.com.

Data lifecycle

Configure a lifecycle rule to delete Reducto objects automatically. Scope it to the bucket folder with matchesPrefix. Omit the prefix only if the bucket holds nothing but Reducto data:

lifecycle.json

{
  "rule": [
    {
      "action": { "type": "Delete" },
      "condition": { "age": 1, "matchesPrefix": ["reducto/"] }
    }
  ]
}

gcloud storage buckets update gs://acme-reducto-data --lifecycle-file=lifecycle.json

A one-day rule outlives result URLs, which expire after 12 hours.

Rotating the key

Create a new key for the same service account.
In Studio, paste the new key into service_account_json for the environment, verify, and save. Saving other changes without a new key keeps the stored key.
Wait 12 hours. Result URLs signed with the old key stop working when you delete it.
Delete the old key: gcloud iam service-accounts keys delete <old-key-id> --iam-account="$SA".

To revoke Reducto’s access immediately, remove the role bindings from the bucket or disable the key.

Network access

Reducto connects to your bucket over the public GCS endpoint (storage.googleapis.com). PrivateLink and Private Service Connect are not supported for GCS. If the project is inside a VPC Service Controls perimeter, contact Reducto before setup, because the perimeter blocks requests from outside it.

Validation checklist

Verify storage access in Studio succeeds for each environment
The service account has only roles/storage.objectAdmin and roles/storage.legacyBucketReader, granted on the bucket:
gcloud storage buckets get-iam-policy gs://acme-reducto-data
The bucket enforces public access prevention and uses uniform bucket-level access

The lifecycle rule is in place:

gcloud storage buckets describe gs://acme-reducto-data --format="default(lifecycle_config)"

Smoke test: Run a small job with the environment selected and check that objects appear under the bucket folder

Troubleshooting

Error	Cause and fix
`service_account_json credentials were not provided`	The environment has no key. Paste the service account JSON key and save again.
`service account credentials are invalid`	The pasted value is not a valid service account key. Paste the complete contents of the JSON key file.
`unable to resolve service account credentials`	Google rejected the key, usually because it was deleted or disabled. Create a new key.
`Access denied — grant Reducto access to this bucket`	The service account lacks a role on the bucket. Grant both roles from step 3. A missing `roles/storage.legacyBucketReader` also causes this error.
`Bucket not found — check the bucket and project`	The bucket name is wrong, or the bucket belongs to a different project.
`The customer storage configuration is invalid` (HTTP 400, on a job)	The environment’s region is in a different residency from the endpoint you called, or the environment has no usable key. Call the endpoint for the environment’s residency, and run Verify storage access again.
`The configured storage credentials could not be used`	Google rejected the key while Reducto read a `gs://` input. Create a new key and save it.
`Access denied reading the document from storage`	The service account cannot read the `gs://` input. Grant `roles/storage.objectViewer` on that bucket, and check that the request selects the GCS environment.

Studio allows about one verification every 30 seconds per organization.

Security

Dedicated identity: Reducto acts only as your service account, never as its own Google identity.
Least privilege: The service account holds two roles on one bucket and nothing at the project level.
Key handling: Reducto never returns the key in API responses or audit logs. You own its rotation and can disable it at any time.
Short-lived links: Every URL that Reducto returns is a signed read-only link to one object that expires after 12 hours.
Automatic cleanup: Lifecycle rules ensure no long-term data persistence.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Hybrid VPC — Google Cloud Storage

How access works

Prerequisites

Setup

Integration values

Data residency

Multiple environments

Usage

Result URLs

Data lifecycle

Rotating the key

Network access

Validation checklist

Troubleshooting

Security

​How access works

​Prerequisites

​Setup

​Integration values

​Data residency

​Multiple environments

​Usage

​Result URLs

​Data lifecycle

​Rotating the key

​Network access

​Validation checklist

​Troubleshooting

​Security

How access works

Prerequisites

Setup

Integration values

Data residency

Multiple environments

Usage

Result URLs

Data lifecycle

Rotating the key

Network access

Validation checklist

Troubleshooting

Security