> For the complete documentation index, see [llms.txt](https://docs.couchdrop.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.couchdrop.io/storage/integrations/google-cloud-storage.md).

# Google Cloud Storage

Learn how to connect to a Google Cloud Storage bucket with Couchdrop

## Overview

Couchdrop can connect directly to a Google Cloud Storage bucket and make that storage available through Couchdrop.

Once connected, you can use the bucket with Couchdrop file transfer and workflow features while keeping files in your existing Google Cloud Storage environment.

## How to connect Google Cloud Storage

{% hint style="warning" %}

### Before you start

To connect Google Cloud Storage, you will need:

* A Google Cloud Storage bucket
* A Google Cloud service account
* A service account JSON key file
* Appropriate Google Cloud Storage permissions for the service account
  {% endhint %}

{% stepper %}
{% step %}

### Configure access to the Google Cloud Storage bucket

Grant the service account access to the Google Cloud Storage bucket you want Couchdrop to use.

For most configurations, assign the **Storage Admin** role to the service account for the bucket.

If you want to use more restrictive permissions, see [Google Cloud Storage permissions](#google-cloud-storage-permissions) below.
{% endstep %}

{% step %}

### Create service account credentials

In Google Cloud Console, navigate to **APIs & Services** > **Credentials**.

Create a service account if required, then create a key for that account and download the associated JSON credentials file.

You will upload this file when configuring the Google Cloud Storage connection in Couchdrop.
{% endstep %}

{% step %}

### Add a new storage connection

In Couchdrop, add a new storage connection and select **Google Cloud** from the list of available connections.
{% endstep %}

{% step %}

### Configure Google Cloud Storage

Enter a **Name for this integration** and select the **Couchdrop folder path** where the connection will appear.

Enter the name of your **Google Cloud Bucket**, then upload the **Service account JSON file** used to access the bucket.

{% hint style="warning" %}
Changing the configured bucket invalidates the uploaded JSON configuration. If you change the bucket, upload the appropriate service account JSON file again.
{% endhint %}

Select **Save and Test** to verify the Google Cloud Storage connection.
{% endstep %}

{% step %}

#### Map your GCS storage location

After the connection has been tested, you can optionally select a specific folder in the bucket to map into Couchdrop. You can also manually enter a path.

Leaving this blank allows Couchdrop to map the storage connection directly without restricting it to a specific folder.

When a folder is selected, Couchdrop limits the connection to that location and its subfolders.
{% endstep %}

{% step %}

#### Save and use your GCS connection

Optionally, configure **Transfer Shield** to surface or block unexpected, non-compliant, or malicious files uploaded through this connection.

When the configuration is complete, save the integration.
{% endstep %}
{% endstepper %}

## Google Cloud Storage permissions

The Google Cloud service account used by Couchdrop must have permission to access and modify objects in the configured bucket.

### Recommended role

For most customers, assign the Google Cloud **Storage Admin** role to the service account for the bucket.

This avoids having to maintain a custom set of individual permissions.

#### Preset IAM roles for buckets without hierarchical namespace

If you want to use Google Cloud preset IAM roles instead of **Storage Admin**, the following roles can be used for buckets that do not use hierarchical namespace:

* **Storage Legacy Bucket Writer**
* **Storage Legacy Object Reader**

#### Minimum individual permissions

If you want to create a custom IAM role with only the individual permissions required by Couchdrop, include:

```
storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.list
storage.objects.get
```

For more information about Google Cloud Storage IAM roles and permissions, see the [Google Cloud Storage IAM roles documentation](https://docs.cloud.google.com/storage/docs/access-control/iam-roles).

### Hierarchical namespace buckets

Google Cloud Storage buckets created with hierarchical namespace require additional permissions because folders are represented as first-class resources.

In addition to the minimum permissions above, grant:

```
storage.folders.create
storage.folders.delete
storage.folders.get
storage.folders.list
storage.folders.rename
storage.objects.move
```

{% hint style="warning" %}
Couchdrop currently has a limitation with Google Cloud Storage hierarchical namespace buckets: folders created outside Couchdrop may not be displayed in Couchdrop.
{% endhint %}

## Frequently asked questions

<details>

<summary>Which Google Cloud permissions should I use?</summary>

For most configurations, assign Storage Admin to the service account for the bucket.\
If your organization requires more restrictive access, you can use the preset roles or individual permissions described in the Google Cloud Storage permissions section.

</details>

<details>

<summary>Do hierarchical namespace buckets require different permissions?</summary>

Yes. Hierarchical namespace buckets require the additional storage.folders.\* permissions and storage.objects.move listed above.

</details>

<details>

<summary>Can I connect more than one Google Cloud Storage bucket?</summary>

Yes. Create a separate Google Cloud connection for each bucket and map each connection to the required Couchdrop folder path.

</details>

<details>

<summary>Do I have to select a folder in the bucket?</summary>

No. Selecting a folder is optional.\
If you leave the folder selection blank, Couchdrop can map the storage connection directly. Selecting a folder restricts the connection to that location and its subfolders.

</details>

<details>

<summary>What happens if I change the Google Cloud bucket?</summary>

Changing the configured bucket invalidates the existing service account JSON configuration. Upload the appropriate JSON file for the new bucket before testing the connection again.

</details>