> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/files/google-cloud-storage-integration.md). # Google Cloud Storage Integration Connect your Google Cloud Storage (GCS) account to Biodock to browse and import biological image files directly from your existing cloud storage. Biodock uses a Google Cloud service account that you create and control. The service account receives read access to the buckets you choose, and you provide its JSON key to Biodock to establish the connection. Once connected, Biodock can browse the authorized storage locations and import selected files into your Biodock workspace. *** ### Before you start You will need: * A Google Cloud project * A Google Cloud Storage bucket * Permission to create a service account and configure IAM permissions * At least one supported image file in your bucket Supported files include: **Single-file formats** * `.tif` * `.tiff` * `.svs` * `.jpg` * `.png` * `.ndpi` **Multi-file formats** * `.mrxs` with its associated data folder * `.vsi` with its associated data folder * `.zip` containing a `.vsi` file and its data folder *** ## Set up Google Cloud The integration requires two levels of Google Cloud IAM access: 1. **Project-level access** — allows Biodock to display the buckets available in your Google Cloud project. 2. **Bucket-level access** — allows Biodock to browse and read files from the specific buckets you authorize. The project-level permission exposes bucket names only. Access to the contents of a bucket is granted separately for each bucket. *** ### 1. Create a service account Open the Google Cloud Console and navigate to: **IAM & Admin → Service Accounts** Make sure the correct Google Cloud project is selected. Click: **Create Service Account** Enter a name such as: `biodock-import` Then click: **Create and Continue** You do not need to assign a project role during this step. Skip **Grant this service account access to project**, then click: **Continue → Done** After creating the service account, copy its email address. It will look similar to: `biodock-import@your-project-id.iam.gserviceaccount.com` You will use this email when configuring permissions in the next steps. *** ### 2. Allow Biodock to list your buckets Navigate to: **IAM & Admin → IAM** Click: **Grant Access** Under **New principals**, paste the service account email you created. Under **Assign roles**, select: **Storage Bucket Viewer** If available in your Google Cloud environment, **Storage Legacy Bucket Reader** can also be used. Click: **Save** This permission allows the integration to retrieve the list of buckets in the Google Cloud project. It does not by itself grant access to the files stored inside those buckets. *** ### 3. Grant access to the bucket you want to use Now grant read access only to the specific bucket or buckets that you want to connect to Biodock. Navigate to: **Cloud Storage → Buckets** Select your bucket. Open: **Permissions** Click: **Grant Access** Under **New principals**, enter the same service account email. Under **Assign roles**, select: **Storage Object Viewer** Click: **Save** Repeat this step for each bucket you want to make available in Biodock. The Storage Object Viewer permission allows Biodock to browse the objects in the bucket and read the selected files for import. *** ### 4. Create a service account JSON key Return to: **IAM & Admin → Service Accounts** Select the service account you created. Open: **Keys** Then select: **Add Key → Create new key** Choose: **JSON** Click: **Create** Google Cloud will download a `.json` file to your computer. Keep this file secure. The JSON key authenticates as the service account and inherits the permissions assigned to that service account. *** ## Connect Google Cloud Storage to Biodock Once your Google Cloud configuration is complete: 1. Log in to **Biodock**. 2. Open **Files**. 3. Select the **Google Cloud Storage** tab. 4. Open the JSON key file you downloaded from Google Cloud. 5. Copy the **entire contents** of the JSON file. 6. Paste the JSON into the Google Cloud Storage connection field in Biodock. 7. Click **Connect**. After the credentials are validated, Biodock will display the Google Cloud Storage buckets available to the service account. > **Important:** Copy the complete JSON file, including the opening `{`, closing `}`, and the complete `private_key` field. *** ## Import files into Biodock After connecting Google Cloud Storage: 1. Select a bucket. 2. Navigate through folders as needed. 3. Select the files or folders you want to import. 4. Click **Import to Biodock**. 5. Select the destination folder in your Biodock workspace. 6. Click **Import here**. Import progress will appear in the upload tray. Once processing is complete, the imported files will appear under **My Files** in Biodock. *** ## Permissions used by the integration | Biodock action | Google Cloud permission | Scope | | ------------------------ | ----------------------- | ----------------- | | Display your buckets | `storage.buckets.list` | Project | | Browse files and folders | `storage.objects.list` | Authorized bucket | | Import a file | `storage.objects.get` | Authorized bucket | If the project-level permission is missing, Biodock will not be able to display the project's bucket list. If the bucket-level **Storage Object Viewer** permission is missing, Biodock may be unable to browse or import files from that bucket. *** ## Connecting multiple buckets You can give Biodock access to more than one Google Cloud Storage bucket. For each additional bucket: 1. Open the bucket's **Permissions** settings. 2. Add the same service account. 3. Assign **Storage Object Viewer**. This lets you control access on a bucket-by-bucket basis without granting the service account read access to every bucket in your project. *** ## Disconnect Google Cloud Storage To disconnect the integration, open the Google Cloud Storage browser in Biodock and click: **Disconnect** Biodock will clear the stored Google Cloud credentials, and you will be returned to the connection screen the next time you open the integration. If you also want to revoke access at the Google Cloud level, you can remove the service account's IAM permissions or disable/delete its key from the Google Cloud Console. *** ## Troubleshooting ### No buckets appear If Biodock reports that the service account does not have: `storage.buckets.list` the service account is missing the project-level bucket listing permission. Return to: **IAM & Admin → IAM** and assign **Storage Bucket Viewer** to the service account. *** ### Files cannot be imported If you see: **Failed to import images from Google Cloud Storage. Please ensure your service account has read permissions on the selected objects.** the service account does not have sufficient access to the contents of the selected bucket. Open the bucket's permissions and assign: **Storage Object Viewer** to the service account. *** ### Missing `private_key` If Biodock reports a missing `private_key`, the complete JSON key was not pasted into Biodock. Open the downloaded `.json` file and copy everything from the opening: `{` through the closing: `}` The JSON must include the complete `private_key` value. *** ### Google Cloud rejects the service account email If Google Cloud displays: **Email addresses and domains must be associated with an active Google Account** verify that you copied the actual service account email from: **IAM & Admin → Service Accounts** Do not manually replace parts of the email with placeholders such as `PROJECT-ID`. *** ### Storage Legacy Bucket Reader is unavailable Some versions of the Google Cloud Console may not show legacy roles. Use: **Storage Bucket Viewer** instead. This provides the bucket-listing permission needed by the Biodock integration. *** ## Security The Google Cloud Storage integration is designed so that you control which storage resources Biodock can access. The service account is created within **your Google Cloud project**, and access to file contents is granted separately for each bucket. Biodock does not require permission to create, modify, or delete objects in your Google Cloud Storage buckets. The service account JSON credentials entered into Biodock are encrypted at rest and decrypted when required to communicate with the Google Cloud Storage API. When a file is imported, Biodock reads the selected object from Google Cloud Storage and transfers it into Biodock's storage, where it proceeds through the standard Biodock file processing pipeline. *** ### Need help? If you have trouble connecting Google Cloud Storage, contact the Biodock team and include: * The error message displayed in Biodock * The Google Cloud project ID * The affected bucket name For security, **do not send your service account JSON key, private key, or other credentials to support by email or chat.** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.biodock.ai/files/google-cloud-storage-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.