Integrate with Google Cloud Storage

This page explains how to authorize a Zilliz Cloud GCP BYOC or BYOC-I project to access an external Google Cloud Storage bucket. You create a custom IAM role in the bucket's Google Cloud project and grant that role to the service account generated by Zilliz Cloud.

📘Notes

Zilliz Cloud displays a service account email for the selected BYOC data plane. Grant that principal bucket-level access. Do not create, download, or upload a long-lived service account key.

Access flow

Before you start

Ensure that:

• Your GCP BYOC or BYOC-I data plane is running.

• You have Organization Owner or Project Admin access to the Zilliz Cloud project.

• You can create a project-level custom IAM role in the Google Cloud project that owns the bucket.

• You can update the IAM policy on the target Cloud Storage bucket.

• The bucket uses a single Region that matches the selected BYOC data plane Region.

📘Notes

A bucket integration is Region-specific. Multi-region and dual-region buckets do not match a single BYOC data plane Region. Use a regional bucket in the data plane's Region.

Step 1: Start the integration in Zilliz Cloud

1

Log in to the Zilliz Cloud console.

2

Open your GCP BYOC project and select Integrations in the left navigation.

3

Under Google Cloud Storage, click + Integration.

4

Enter a unique Integration Name and, optionally, an Integration Description.

5

Click Next.

Step 2: Create a custom Cloud Storage role

1

In the Google Cloud console, select the project that owns the external bucket.

2

Open IAM & Admin > Roles and click + Create role.

3

Enter a title such as Zilliz Bucket Integration, add the following permissions, and create the role.

plaintext

storage.buckets.get
storage.objects.create
storage.objects.list
storage.objects.get

Permission	Purpose
storage.buckets.get	Read bucket metadata and validate its location.
storage.objects.get	Read objects for external volumes and other read workflows.
storage.objects.list	List objects and prefixes in the bucket.
storage.objects.create	Write new objects for export and log-forwarding workflows.

Step 3: Specify the external Cloud Storage bucket

1

Return to Zilliz Cloud and click Next.

2

In Region, select the Region of the BYOC data plane that will access the bucket.

3

In the Cloud Storage Buckets page, confirm that the target bucket uses the same Region.

4

In Bucket Name, enter only the bucket name. Do not include gs://, an object prefix, or a trailing slash.

5

Click Next.

Step 4: Grant the generated service account access

1

On the target bucket's details page, open the Permissions tab.

2

Select View by principals and click + Grant access.

3

Copy the Google Cloud Service Account email displayed by Zilliz Cloud and paste it into New principals.

4

Under Assign roles, select the custom role created in step 2.

5

Click Save.

plaintext

Principal
<ZILLIZ_GENERATED_SERVICE_ACCOUNT>@<PROJECT_ID>.iam.gserviceaccount.com

Role
projects/<BUCKET_PROJECT_ID>/roles/<CUSTOM_ROLE_ID>

Scope
Target Cloud Storage bucket

📘Notes

Do not substitute the BYOC node service account, storage service account, or another project principal. The displayed identity is generated specifically for the bucket integration flow.

Step 5: Validate and add the integration

1

Return to Zilliz Cloud and click Validate Integration.

2

If you granted the role recently, allow time for Google Cloud IAM propagation and retry validation.

3

When the status changes to Successful, click Add. The Google Cloud Storage integration is now available to supported workflows in the same Zilliz Cloud project and Region.

Security recommendations

• Create a dedicated custom role for bucket integrations and keep it limited to the four listed permissions.

• Grant the role on the target bucket rather than at project or organization scope.

• Keep Public Access Prevention enabled unless another workload has an explicit requirement.

• Do not create a service account key. The integration uses a generated service account and short-lived credentials.

• If an organization policy, IAM deny policy, VPC Service Controls perimeter, or Cloud KMS policy applies, ensure it permits the required data path.

Troubleshooting

Validation result	Likely cause	What to check
bucket region not match	The bucket location differs from the selected BYOC data plane Region.	Use a regional bucket in the exact data plane Region.
verify bucket access failed	The service account cannot read bucket metadata.	Confirm the custom role contains storage.buckets.get and is granted on the correct bucket.
Principal not found	The generated service account has not propagated yet or was copied incorrectly.	Copy the email again from Zilliz Cloud, wait briefly, and retry the IAM grant.
Integration validates but a later workflow cannot read or write	An object permission is missing or blocked by another policy.	Check storage.objects.get, storage.objects.list, and storage.objects.create, plus organization deny and KMS policies.